Call the MCP server

POST/mcp

Chartnaut's remote MCP server. MCP clients such as Claude, ChatGPT and Cursor send it JSON-RPC 2.0 messages to list and call its tools. Point your MCP client at https://api.chartnaut.com/v1/mcp; Connect Chartnaut to an AI app covers the apps, the MCP tools reference covers each tool, and How the MCP server works follows a call and the sign-in step by step.

Scope	Heavy call	Long poll	CLI
Each tool's own	Per tool	Tools wait up to 25 s	`chartnaut mcp install`

Guidance

The transport is Streamable HTTP, stateless, with plain JSON answers. Every message is its own POST. The server keeps no session, sends no Mcp-Session-Id, and answers GET with 405. A DELETE carrying an Mcp-Session-Id gets 204 and changes nothing.
Authenticate with an OAuth access token from Get a token, or an API key. Both go in Authorization: Bearer. Without one, the answer is 401 with a WWW-Authenticate header whose resource_metadata points at Get protected resource metadata, which is how an MCP client finds the sign-in.
Send Accept: application/json, text/event-stream. The server answers in JSON, but a request that does not accept both types is refused with 400.
The envelope itself costs nothing: initialize, tools/list, prompts/list, prompts/get and resources/list count toward no limit. Each tool call, and each resources/read, is served as the API requests behind it, and each of those counts once toward your requests a minute, with the same scopes, heavy-call and plan checks as a direct call. Limits and cost lists them per tool.
A tool that is refused returns a JSON-RPC result with isError: true and a text starting Error <code>:, so the model can correct itself. Protocol mistakes, such as an unknown method, are JSON-RPC errors.
A browser request must come from an allowed origin: claude.ai, chatgpt.com, Chartnaut's own sites, or localhost for tools such as the MCP Inspector. Requests with no Origin, from servers and CLIs, are accepted. Any other origin gets 403 forbidden.
One request can carry up to 3 MB. Each tool result is capped at 40 KB of text; see Output limits.

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer` and an OAuth access token (`cn_oat_…`) or an API key (`cn_live_…`)
`Accept`	Yes	Must list both `application/json` and `text/event-stream`
`Content-Type`	Yes	`application/json`
`MCP-Protocol-Version`	No	The protocol version agreed in `initialize`, such as `2025-06-18`

Request body

One JSON-RPC 2.0 message.

Field	Type	Required	Description
`jsonrpc`	string	Yes	`2.0`
`id`	integer or string	For requests	Omitted on notifications
`method`	string	Yes	Such as `initialize`, `tools/list`, `tools/call`, `prompts/get` or `resources/read`
`params`	object	Depends on `method`	For `tools/call`: `name` and `arguments`

Response

200 with the JSON-RPC response. A tool call's result has content, a list with one text item holding compact JSON or markdown, and isError when the tool was refused. A notification gets 202 with no body.

Status codes

Status	Code	Meaning
`200`	-	The JSON-RPC response, including tool errors
`202`	-	A notification was accepted
`400`	-	Not valid JSON-RPC, the `Accept` header lacks a type, or `MCP-Protocol-Version` names a version the server does not support
`401`	`unauthorized`	No bearer token, or it is wrong, expired or revoked. Follow `WWW-Authenticate` to sign in again
`403`	`forbidden`	The browser `Origin` is not allowed, or the account is on the waitlist
`403`	`plan_limit`	The account is on Free
`405`	-	`GET`, or any method other than `POST` and `DELETE`. Only `POST` carries messages
`429`	`rate_limited`	More than 30 failed token checks from your IP address in a minute
`500`	-	The request is over 3 MB: the server stops reading it and answers failed to read body

Example request

Call the list_instruments tool with an API key.

curl https://api.chartnaut.com/v1/mcp \
  -H "Authorization: Bearer cn_live_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_instruments",
      "arguments": { "q": "bitcoin", "limit": 1 }
    }
  }'

Example response

200 OK

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"instruments\":[{\"category\":\"crypto\",\"coverage\":{\"end\":\"2026-09-27T12:00:00Z\",\"start\":\"2024-09-27T00:00:00Z\"},\"name\":\"Bitcoin\",\"order_flow\":true,\"short\":\"BTC\",\"symbol\":\"HYPERLIQUID:BTC\"}],\"next_cursor\":\"1\"}"
      }
    ]
  }
}

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing bearer token. Connect Chartnaut through your MCP client's sign-in, or send an API key from Settings → Developers."
  }
}

From the CLI

chartnaut mcp install claude

The CLI makes no MCP calls itself. chartnaut mcp install prints the setup for Claude Code, Cursor or Codex with your API address filled in, and --write applies it. Command reference