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

# MCP overview

> The PolyTape MCP server — endpoint, transport, connecting, and the caching rule that bites everyone once.

```
https://api.polytape.io/mcp
```

FastMCP over **streamable HTTP**, stateless. **13 tools and one prompt.**

Works in Claude Code, Cursor, Windsurf, opencode, the claude.ai custom
connector, and any MCP client.

## Connecting

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http polytape https://api.polytape.io/mcp \
      --header "Authorization: Bearer td_live_..."
    ```
  </Tab>

  <Tab title="claude.ai">
    **Settings → Connectors → Add custom connector**, then the server URL:

    ```
    https://api.polytape.io/mcp
    ```

    Authorize over OAuth — you sign in with your PolyTape account, and no key is
    pasted.
  </Tab>

  <Tab title="opencode">
    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "polytape": {
          "type": "remote",
          "url": "https://api.polytape.io/mcp",
          "oauth": false,
          "headers": { "Authorization": "Bearer td_live_..." }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    ```json theme={null}
    {
      "mcpServers": {
        "polytape": {
          "url": "https://api.polytape.io/mcp",
          "headers": { "Authorization": "Bearer td_live_..." }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Both credential families work: a `td_live_` key in the `Authorization` header, or
OAuth where your client supports it. See [Authentication](/authentication).

<Warning>
  **Re-add the connector after an API update.** MCP clients cache `tools/list`,
  so new tools and sharpened tool descriptions never reach a client that
  connected before the change — it will keep using the old contract and never
  tell you.

  If a tool you expect is missing, or a tool behaves like an older version of
  itself, remove the connector and add it again. Reconnecting spends no budget.
</Warning>

## What a call costs

<Columns cols={2}>
  <Card title="Free" icon="check">
    Connecting · `tools/list` · `prompts/list` · fetching the
    `crack_this_trader` prompt.

    A Basic user does not spend part of their 50 just to plug in.
  </Card>

  <Card title="1 request" icon="coins">
    Every tool **call**, `get_chart_template` included. There are no exemptions.
  </Card>
</Columns>

MCP and REST draw on the **same per-user budget** — see
[Plans & limits](/plans-and-limits).

<Note>
  **Tools return their payload twice** — as readable text *and* as structured
  JSON. That is convenient, and it means paged tools cost roughly **double** their
  REST equivalent. Pass `limit` / `points` wherever a tool offers one.
</Note>

## Conventions

* `trader` accepts a **0x wallet**, a **polymarket.com profile URL**, or a
  **display name**. Responses echo the canonical wallet and name.
* `market` is the `0x…` 64-hex condition id from `list_trader_markets` or
  `get_top_markets`.
* Timestamps are epoch **seconds**. Money fields are USD. Prices are
  UP-normalized (0–1).

## Errors come back readable

Failures arrive as tool results (`isError: true` with text), never as opaque
protocol errors.

| Text you'll see                                                   | What it means                                                                                                                             |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `rate limit: retry in Ns`                                         | Transient. Wait N seconds and retry.                                                                                                      |
| A message naming an upgrade and `polytape.io/pricing`             | **The paywall** — daily (Basic) or monthly (Pro/Max) quota spent, or the Basic 3-wallets-a-day cap. Relay it to your human; do not retry. |
| `this market is outside your history window`                      | The depth gate — Basic sees 5 markets per trader. Surface the upgrade, or treat it as a not-found.                                        |
| `no such tape in your library` / `no such market for this trader` | A 404-equivalent.                                                                                                                         |
| `the trader archive is not available…` / `pm_offline`             | A transient upstream blip. Retry shortly; for `pm_offline`, fall back to the archive P/L fields.                                          |

Full table with HTTP codes: [Errors](/errors).

<Card title="The 13 tools" icon="wrench" href="/mcp/tools" horizontal>
  Signatures, what each returns, and when to reach for it.
</Card>