MCP server for AI agents

What it is

POST https://tgmcharts.com/api/v1/mcp is a Model Context Protocol server over streamable HTTP: stateless JSON-RPC 2.0, one JSON response per POST, no sessions and no server-initiated streams (GET and DELETE answer 405, as the streamable-HTTP specification allows for stateless servers). Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are negotiated on initialize.

Methods: initialize, ping, tools/list, tools/call, and notifications (acknowledged with 202). Batches are accepted up to 20 messages. Every response is Cache-Control: no-store.

The tools are thin wrappers over the same builders the REST endpoints use — MCP and REST cannot disagree — and read stored, precomputed data only.

Connect

Discovery (initialize, tools/list, ping) needs no key. tools/call needs an API key — the free tier works, no card — sent as Authorization: Bearer tgm_live_…. Mint one at /developers/keys.

claude mcp add --transport http tgmcharts https://tgmcharts.com/api/v1/mcp \
  --header "Authorization: Bearer tgm_live_YOUR_KEY"

{
  "mcpServers": {
    "tgmcharts": {
      "type": "http",
      "url": "https://tgmcharts.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer tgm_live_YOUR_KEY" }
    }
  }
}

curl -s https://tgmcharts.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The seven tools

Results carry the machine shape in structuredContent and the same JSON serialized in content[0].text. Honest states — symbol not covered, a metric outside the tier, compare on a line chart — come back as readable text with isError: true; argument-schema violations are JSON-RPC -32602 errors.

Screener fields

screen_stocks filters and sorts on: symbol, name, sector, marketCap, peRatio, dividendYield, consecutiveYears, netProfitMargin, grossMargin, revenueGrowth, debtToEquity, priceChange1Y, percentFrom52WeekHigh, percentFrom52WeekLow, revenueCagr5y, netIncomeCagr5y, epsCagr5y, fcfCagr5y, dividendsCagr5y.

A keyed tools/call

Each tools/call in the body is metered at 2 units against the key's tier quota; keyed responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window.

curl -s https://tgmcharts.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tgm_live_YOUR_KEY" \
  -d '{"jsonrpc": "2.0","id": 1,"method": "tools/call","params": {"name": "get_metric_series","arguments": { "symbol": "KO", "metric": "pe-ratio", "years": 10, "max_points": 60 }}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_metric_series",
    "arguments": { "symbol": "KO", "metric": "pe-ratio", "years": 10, "max_points": 60 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [ { "type": "text", "text": "<the same JSON as structuredContent, serialized>" } ],
    "structuredContent": { …series body…, "points": [ … ≤ max_points … ], "downsampledTo": integer | null },
    "isError": false            // true + a readable text explanation for honest states (symbol not covered, non-series metric)
  }
}

401 and 429

A tools/call without a key answers HTTP 401 with a JSON-RPC error and a WWW-Authenticate: Bearer realm="tgmcharts-api", error="missing_token" header. A malformed, unknown or revoked key answers 401 with { "error": "Invalid API key", … }. An exhausted quota answers 429 with Retry-After — the same body as the REST endpoints, shown on authentication and limits.

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "tools/call requires an API key — the free tier works (no card): mint one at https://tgmcharts.com/developers/keys and send it as Authorization: Bearer tgm_live_… . Lifecycle methods (initialize, tools/list, ping) need no key."
  }
}

Not using MCP?

Frameworks that build tools from an OpenAPI document can use /api/v1/openapi.json — every metric slug is enumerated in the path parameters, and the x-tgmcharts-metrics extension carries the full catalogue in one fetch. A worked example is in the quickstarts.