> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tradingapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect over MCP

> Connect Claude, Cursor, Codex or another MCP client to the Trading API, with limits you choose when you sign in.

The Trading API has a remote MCP server, so an AI client can find markets, preview and place orders, and read positions without writing any HTTP. You connect once, choose what the connection may do, and the client gets nine tools.

```text theme={"system"}
https://tradingapi.dev/mcp
```

To have an AI agent set it up for you, in any client, ask it: "Read [https://tradingapi.dev/connect.md](https://tradingapi.dev/connect.md) and connect me to Trading API." That page tells the agent how to add the server and what you do to sign in.

The server speaks Streamable HTTP and runs only remotely. It implements MCP protocol version `2026-07-28`, and we negotiate older clients down to a version they support.

## Connecting with OAuth

Add the URL to your client, and the client opens a sign-in page. After you sign in, a consent screen asks what the connection may do:

* **Read only** lets the client read markets, your account, positions, orders and fills.
* **Trade** also lets it place orders and close positions. You choose the markets it may trade, its largest order (at most the platform cap, \$25 today) and its total value per 24 hours.
* **Ask me to confirm each order** is optional. If you turn it on, the client asks you before each order. See [Confirming orders](#confirming-orders).

The sign-in must be recent: if you signed in more than 15 minutes ago, you're asked to sign in again before the consent screen.

### Claude

In Claude, open **Settings > Connectors**, choose **Add custom connector**, and paste `https://tradingapi.dev/mcp`.

### Claude Code

```bash theme={"system"}
claude mcp add --transport http tradingapi https://tradingapi.dev/mcp
```

Then run `/mcp` in Claude Code, choose `tradingapi` and sign in.

### Cursor

Add the server to `~/.cursor/mcp.json`:

```json theme={"system"}
{
  "mcpServers": {
    "tradingapi": {
      "url": "https://tradingapi.dev/mcp"
    }
  }
}
```

### Codex

```bash theme={"system"}
codex mcp add tradingapi --url https://tradingapi.dev/mcp
```

If Codex doesn't open the sign-in page, run `codex mcp login tradingapi`.

## Connecting with an API key

If there's no browser to sign in with, such as on a server, send an existing [API key](/concepts/api-keys) as a bearer token instead. The connection then has that key's limits.

<CodeGroup>
  ```bash Claude Code theme={"system"}
  claude mcp add --transport http tradingapi https://tradingapi.dev/mcp \
    --header "Authorization: Bearer tapi_..."
  ```

  ```bash Codex theme={"system"}
  export TRADINGAPI_KEY=tapi_...
  codex mcp add tradingapi --url https://tradingapi.dev/mcp \
    --bearer-token-env-var TRADINGAPI_KEY
  ```

  ```json Cursor theme={"system"}
  {
    "mcpServers": {
      "tradingapi": {
        "url": "https://tradingapi.dev/mcp",
        "headers": { "Authorization": "Bearer tapi_..." }
      }
    }
  }
  ```
</CodeGroup>

## Managing connections

Each OAuth connection is a grant. Grants appear on the [account page](https://tradingapi.dev/account) beside your API keys. There you can change a grant's limits (giving a read-only grant limits lets it trade), turn confirmation of each order on or off, or revoke it, and it stops working immediately. A grant can't withdraw money or change its own limits.

## Tools

| Tool | Arguments | What it does |
| - | - | - |
| `find_markets` | `query?` | Lists markets, or searches them by name, symbol and common aliases. |
| `get_account` | | Returns the account, this grant's limits and how much of its 24-hour value remains. |
| `get_positions` | `market?` | Returns open positions, or the one in `market`. |
| `preview_order` | `market`, `side`, `value`, `type?`, `price?`, `reduce_only?` | Checks an order and estimates its fill without placing it. See [Previewing orders](/guides/preview). |
| `place_order` | the same, plus `client_order_id?` | Places an order and waits up to 10 seconds for the outcome. |
| `close_position` | `market`, `percent?` or `value?`, `client_order_id?` | Closes all or part of a position. |
| `get_order` | `order_id` or `client_order_id` | Returns one order. |
| `list_orders` | `market?`, `status?`, `limit?`, `cursor?` | Lists orders, newest first. |
| `list_fills` | `market?`, `order_id?`, `limit?`, `cursor?` | Lists fills, newest first. |

`place_order` and `close_position` are marked destructive, so most clients ask you before calling them. The other tools are marked read-only.

The arguments mean the same as the fields of the HTTP API. For example, `value` is in US dollars, and `type` is `market` or `limit`. Unlike the HTTP API, the tools default `type` to `market`. See [Orders](/concepts/orders).

## Retries and duplicates

`client_order_id` is optional. If you leave it out, we derive one from the grant and the order's terms. If the client sends an identical order again within a minute of the first, or while the first is still pending, we return the first order instead of placing a second, and the result has a note saying so. Metadata counts as part of the order. Identical calls that arrive at the same moment also become one order. This protects you from a model that calls the same tool twice.

To place a second identical order on purpose, give it a `client_order_id` of your own, one you haven't used before. Sending that same ID again is then a safe retry of that order. A rejected order isn't returned as a duplicate: nothing of it filled, so sending it again places a new order.

If you pass your own `client_order_id`, it works as it does in the HTTP API. See [Retries and idempotency](/guides/retries).

## Confirming orders

If you turned on **Ask me to confirm each order**, `place_order` and `close_position` first ask you through the client, showing the preview's numbers. We place the order only after you accept; if you decline, the tool returns the error `order_declined`. A retry of an order you already accepted returns it without asking again.

This uses MCP elicitation, which needs a client on protocol `2026-07-28` or later. If a client can't ask, the tool returns the error `confirmation_unavailable` and places nothing.

The client asks the question and passes on your answer. Confirmation therefore protects you from a model placing an order you didn't mean; it can't protect you from a client that lies about your answer. The grant's limits apply whatever the client does, so give a connection only the limits you would accept it using in full.

## Errors

When a tool fails, its result has `isError` set and carries the same error object as the HTTP API, with `code`, `message`, `hint` and `retryable`. See [Errors](/api-reference/errors) for every code and [Handling errors](/guides/errors) for how to respond.

## What MCP can't do

The MCP server can't withdraw money, create API keys or change limits. You do those on the [account page](https://tradingapi.dev/account).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.