MCP

Connect

One hosted MCP server. Add the URL and your bearer token to a client that can send an HTTP header. The assistant then calls the same derived-analytics routes as REST. Nothing to install on a server of your own.

What is the MCP server?

The TanukiTrade MCP server lets Claude, Cursor, and other Model Context Protocol clients query derived options analytics in plain language. Each enabled REST route is one tool. The tool name is the operation id. The arguments are the REST JSON body. The bearer token stays on the HTTP request.

The server is stateless. There is no session id and no long-lived SSE stream. Every call is one POST of a JSON-RPC body, and the response is one JSON document. serverInfo.name is tanukiapi.

Why connect it

Four jobs that fit a conversation with an assistant that can call the tools itself.

Server details

MCP and REST are different hosts. Do not append /mcp/v1 to the REST base URL.

https://mcp.tanukitrade.com/mcp/v1

The token is the client id, a dot, then the key. The client id is 8 lowercase letters or digits. The key is 16 to 128 letters or digits. The whole token is at most 160 characters, case-sensitive, and not trimmed. YOUR_CLIENT_ID.YOUR_API_KEY is a placeholder. It is not a secret and it is not a working token.

Sign in and copy the token from API Access (/webapp/developer/api/). REST and MCP use that same token. There is no second credential, no OAuth, and no cookie. Do not put the token in a URL, a query string, a tool argument, a log line, or a chat.

POST https://mcp.tanukitrade.com/mcp/v1
Authorization: Bearer YOUR_CLIENT_ID.YOUR_API_KEY
Content-Type: application/json
Accept: application/json

initialize, tools/list, resources/list, and resources/read each spend one rate-limit attempt and do not add endpoint usage. A successful tool call spends an attempt and counts as usage, the same as the matching REST route. RateLimit-Limit is the budget this server is enforcing. RateLimit-Reset is seconds until the next ET minute, not a timestamp. On 429, wait at least Retry-After seconds. Headers are on Rate limits and headers.

Connect your client

1. Copy the token from API Access while you are signed in.
2. Paste one config below. Every working client needs the same three things: the URL, the Authorization header, and a server name. The snippets use YOUR_CLIENT_ID.YOUR_API_KEY.
3. Restart the client, then ask it to list SPX, AAPL, and /ES1 with TanukiTrade. A 401 is an HTTP authentication failure before JSON-RPC. Check the full bearer token and the header, not the tool arguments.

The signed-in API Access page can also hand the config to Cursor or VS Code on your own computer. Do not share or paste that install link. It contains the token. The blocks on this page do not.

Claude Code

Claude Code speaks remote HTTP with a custom header. -s user stores the server for every project on this machine. -s local keeps it in the current repo. Do not commit a project file that still has the real token.

claude mcp add --transport http -s user tanuki-pro https://mcp.tanukitrade.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_CLIENT_ID.YOUR_API_KEY"

Start claude and run /mcp. tanuki-pro should be connected. A header you set yourself does not fall through to an OAuth login: a bad token is a failed connection, usually HTTP 401.

Claude Desktop

Claude Desktop's config file runs local stdio servers. This server is remote and uses a bearer token, so the config starts the mcp-remote bridge. That needs Node.js and downloads the package through npm the first time.

Open Settings → Developer → Edit Config. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is %APPDATA%\Claude\claude_desktop_config.json. Merge the block, then quit Claude Desktop completely and reopen it.

The header value has no space after the colon. mcp-remote documents that a space inside args is mangled on Windows. The token itself, including the Bearer scheme, lives in env.

{
  "mcpServers": {
    "tanuki-pro": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.tanukitrade.com/mcp/v1",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_CLIENT_ID.YOUR_API_KEY"
      }
    }
  }
}

The built-in Add custom connector screen expects OAuth and, on most accounts, has nowhere to put a bearer token. Use the config file. If your account shows a request-headers field, the header name is Authorization and the value is Bearer YOUR_CLIENT_ID.YOUR_API_KEY, scheme included. Claude sends that value exactly as you type it.

Cursor

Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project. Do not commit the project file while it contains the real token. Cursor also expands ${env:TANUKI_TOKEN} in headers if you would rather keep the token in the environment.

{
  "mcpServers": {
    "tanuki-pro": {
      "url": "https://mcp.tanukitrade.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_CLIENT_ID.YOUR_API_KEY"
      }
    }
  }
}

Open Settings → MCP. tanuki-pro should show a green dot. There is no type field. A url is the remote HTTP server.

VS Code

Workspace config is .vscode/mcp.json and uses a top-level servers object. User config is Command Palette → MCP: Open User Configuration. A portable .mcp.json in the repo root uses mcpServers instead. Do not paste this block into that other shape.

{
  "servers": {
    "tanuki-pro": {
      "type": "http",
      "url": "https://mcp.tanukitrade.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_CLIENT_ID.YOUR_API_KEY"
      }
    }
  }
}

Run MCP: List Servers from the command palette. To keep the token out of the file, set the header to Bearer ${input:tanuki-token} and add an inputs entry with "type": "promptString" and "password": true.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json, or use Settings → Cascade → MCP Servers. Remote entries use serverUrl, not url. Quit Windsurf completely and reopen it. If the product on your machine was renamed, use that install's MCP settings; the entry still needs serverUrl and the Authorization header.

{
  "mcpServers": {
    "tanuki-pro": {
      "serverUrl": "https://mcp.tanukitrade.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_CLIENT_ID.YOUR_API_KEY"
      }
    }
  }
}

Gemini CLI

Add the block to ~/.gemini/settings.json and restart the CLI. httpUrl is the streamable HTTP field. In current Gemini CLI docs, url alone is the SSE field, so do not swap them. /mcp lists the loaded servers. Avoid an underscore in the server name.

{
  "mcpServers": {
    "tanuki-pro": {
      "httpUrl": "https://mcp.tanukitrade.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_CLIENT_ID.YOUR_API_KEY"
      }
    }
  }
}

Any other client

A client that can do streamable HTTP and a custom header needs only the URL and this header. OAuth-only connectors cannot send the token. See the next section.

{
  "transport": "streamable-http",
  "url": "https://mcp.tanukitrade.com/mcp/v1",
  "headers": {
    "Authorization": "Bearer YOUR_CLIENT_ID.YOUR_API_KEY"
  }
}

Not yet: ChatGPT and claude.ai

Protocol

The client sends JSON-RPC 2.0. Auth is not a field in that body. A notification, a request with no id, is HTTP 202 and an empty body. An unknown method is HTTP 200 and JSON-RPC -32601.

initialize

{
  "jsonrpc": "2.0",
  "id": "req_init_01",
  "method": "initialize",
  "params": {"protocolVersion": "2025-06-18"}
}

{
  "jsonrpc": "2.0",
  "id": "req_init_01",
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {"tools": {}, "resources": {}},
    "serverInfo": {"name": "tanukiapi", "version": "2025-06-18"},
    "instructions": "Times and dates are America/New_York with a numeric offset. Page with the cursor argument; meta.page only locates the current page. Call only arguments named in the tool schema. On DATA_WARMING, wait and retry. On 429, honor Retry-After. If a description is not enough, resources/read one tanuki://docs/v1 uri. The bearer token is already on the HTTP request."
  }
}

Ask for 2025-03-26 or 2025-06-18. Any other string is answered as 2025-03-26. serverInfo.version is that chosen protocol version. The instructions string is short on purpose. It does not repeat the tool catalog.

tools/list

No cursor returns the tools this token may call, in route order. A default PRO token receives every group. An explicit group list omits the rest. A non-empty params.cursor returns an empty tool list. Each tool has name, description, inputSchema, and outputSchema. Both schemas are type: object. inputSchema has additionalProperties: false. outputSchema requires a boolean ok and is either the success envelope (data, meta) or the error envelope (error).

{
  "jsonrpc": "2.0",
  "id": "req_tools_list_01",
  "method": "tools/list",
  "params": {}
}

Short markdown for one tool is resources/read on a tanuki://docs/v1 URI. Both resource calls are bearer-protected. The list is on Resources.

tools/call

This is the same call as POST /api/v1/discovery/expiries. On success, structuredContent is the HTTP envelope and the text content is ok.

{
  "jsonrpc": "2.0",
  "id": "req_expiries_01",
  "method": "tools/call",
  "params": {
    "name": "list_expiries",
    "arguments": {"symbol": "SPX"}
  }
}

Domain error

A domain failure is still a JSON-RPC result, not a JSON-RPC error. isError is true. structuredContent is the same error envelope as REST. The text content is the error message. The HTTP status is the domain status. Unknown symbol is HTTP 422.

{
  "jsonrpc": "2.0",
  "id": "req_expiries_01",
  "result": {
    "content": [{"type": "text", "text": "Unknown symbol."}],
    "structuredContent": {
      "ok": false,
      "error": {
        "code": "UNKNOWN_SYMBOL",
        "message": "Unknown symbol.",
        "request_id": "req_example_01"
      }
    },
    "isError": true
  }
}

An unknown tool name is different. That is HTTP 200 and JSON-RPC -32602 with message Unknown tool. It is not UNKNOWN_SYMBOL.

Disabled tool

A tool that exists but is outside this token's groups is HTTP 403. A default token can call every catalog group, so this code is for an explicit list that leaves the tool out. The body is a tool result, isError true, code ENDPOINT_NOT_ENABLED. The message is This endpoint is not available on your plan yet. The same code on REST is a normal HTTP error envelope, without the JSON-RPC wrapper. Do not retry until the group is on the list. The code list is on Errors.

{
  "jsonrpc": "2.0",
  "id": "req_gamma_01",
  "result": {
    "content": [{"type": "text", "text": "This endpoint is not available on your plan yet."}],
    "structuredContent": {
      "ok": false,
      "error": {
        "code": "ENDPOINT_NOT_ENABLED",
        "message": "This endpoint is not available on your plan yet.",
        "request_id": "req_example_01"
      }
    },
    "isError": true
  }
}

Authentication and rate limits

401 and 429 happen before the body is read as JSON-RPC. The response is the HTTP error envelope, not a result and not isError. Do not look for them inside structuredContent.

How a tool call flows

1. The client sends the call. The assistant picks a tool. The client posts it to https://mcp.tanukitrade.com/mcp/v1 with the bearer token in the header.
2. The server runs the REST route. Same arguments, same validation, same cache, and the same 120-per-minute budget. One tool call is one request.
3. The chat gets the result. Success is the HTTP envelope in structuredContent. A domain failure is that envelope with isError: true. The assistant answers, or it fixes the arguments and calls again.

The server does not remember the previous call. If the assistant fans out across five tickers in parallel, that is five requests in the same minute.

The tool catalog

You rarely name a tool. Describe the question and the assistant matches the description. The table is what tools/list returns for a default PRO token: every group. An explicit group list omits the rest, and calling one of those is HTTP 403 ENDPOINT_NOT_ENABLED. The 3 account tools are always listed. The same catalog is on Tools.

Asking good questions

The assistant picks a tool by matching your words to the tool description.

• Name the concept. IV rank, skew, backwardation, term structure, and implied move into earnings are the words on the tool descriptions.
• Give the tickers. List them: SPX, NVDA, AAPL, /ES1. A symbols array can carry up to 300 names in one call. Futures keep the leading slash.
• Anchor the expiry. Say 0DTE, the next weekly, or the front monthly. Aliases are 0, 1, w1–w4, M1–M3, and ALL.
• Follow up by name. "Now show the term structure for the same two names" keeps the assistant on the tool it just used.
• Keep New York time. Every timestamp is America/New_York with a numeric offset. Do not ask the assistant to rewrite them as Z.

Prompt pack

Copy one prompt after the client shows the TanukiTrade tools. These examples use discovery, fundamentals, or volatility. The other groups are on a default token. They are missing only when an explicit group list leaves them out.

Getting started

Verify the connection list_symbols

Use the TanukiTrade tools to list the symbols SPX, AAPL and /ES1. Tell me which ones exist and their type. If a call fails, show me the exact error code.

What can you do with TanukiTrade?

List every TanukiTrade tool you have access to, one line each, grouped by Discovery, Fundamentals and Volatility. Then suggest three questions I could ask you as an options trader.

Pre-market

Morning volatility brief list_volatility_iv_metrics list_volatility_backwardation_summary list_earnings

For SPX, QQQ, NVDA, TSLA, AAPL and AMZN: get IV rank, IV percentile and the 5-day IVx change, flag any backwardation, and list earnings in the next 7 days with the implied move. Give me a compact table sorted by IV rank, then three bullet takeaways.

Earnings week planner list_earnings list_volatility_iv_metrics

Which of these report earnings in the next 10 days: AAPL, MSFT, NVDA, AMZN, META, GOOGL, TSLA, NFLX? For each one show the date, before/after market, days to earnings, the implied move and current IV rank. Highlight where IV rank is low relative to the implied move.

Volatility

Cheap vs. rich IV screen list_volatility_iv_metrics list_volatility_call_put_skew

Rank SPY, QQQ, IWM, NVDA, AMD, TSLA, META, AAPL, MSFT and AMZN by IV percentile. Split them into "IV cheap" (below 30) and "IV rich" (above 70) and add the call/put skew on the optimal expiry for each. Explain in two sentences what the skew suggests for the rich names.

Term structure check list_volatility_term_structure list_expiries

Show the full term structure (expiry ALL) for SPX: DTE, IVx and backwardation per expiry. Is the curve in contango or backwardation, and where is the kink? Keep times in New York time.

Backwardation alert list_volatility_backwardation_summary

Check weekly and monthly backwardation for SPX, NDX, RUT, TSLA, NVDA and COIN. List only the names currently in backwardation and say whether it is weekly, monthly or both.

Fundamentals

Company snapshot list_fundamentals_profile list_fundamentals_benchmark_correlation

Give me a one-paragraph snapshot of PLTR: sector, industry, market cap, P/E, EPS and dividend yield, plus which benchmark (SPY, QQQ, IWM, TLT, GLD) it correlates with best over 63 days and how strongly.

Is it the stock or the market? list_fundamentals_benchmark_correlation

For NVDA, AMD, SMCI, ARM and AVGO show the best-fit benchmark and the 63-day correlation. Which of them mostly trade like QQQ, and which have their own story right now?

Developer

Turn this into code list_volatility_iv_metrics

Call the IV metrics tool for SPX and AAPL. Then write the equivalent REST request as a curl command and as a short Python script (requests library) against https://api.tanukitrade.com. Read the token from an environment variable called TANUKI_API_TOKEN; never inline it.

TanukiTrade API and MCP. Derived options analytics for your code and for agents. Not investment advice. tanukitrade.com