Connect via MCP & SDKs

Your tengu_ key works over three interfaces — the raw REST API, the Model Context Protocol (for AI agents like Claude), and generated SDKs. All three authenticate the same way, debit the same credit wallet, and honor the same tier gating. Pick whichever fits your stack.

Model Context Protocol (MCP)#

A hosted MCP server exposes the FIRM tool catalogue to AI agents over the Model Context Protocol (Streamable HTTP), so Claude and other agents can call live market & quant data directly.

claude.ai / Claude web (recommended)#

Settings → Connectors → Add custom connector → set the URL to https://firm.tengu.co/mcp and add an X-API-Key header with your key. This is the most reliable path for a hosted, header-authenticated MCP server.

Claude Desktop#

Desktop launches MCP servers as local processes, so bridge to the hosted endpoint with mcp-remote in claude_desktop_config.json — it forwards your auth header:

1{2  "mcpServers": {3    "tengu-firm": {4      "command": "npx",5      "args": ["-y", "mcp-remote", "https://firm.tengu.co/mcp",6               "--header", "X-API-Key:tengu_YOUR_KEY"]7    }8  }9}

Check the endpoint is reachable (listing tools needs no key):

1curl -s -X POST https://firm.tengu.co/mcp \2  -H 'Content-Type: application/json' \3  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

Once connected, ask Claude something like "use tengu-firm to pull Ford's recent bond prints" and it will call the matching tool, billed to your wallet.

OpenAPI spec#

A curated public OpenAPI 3.1 spec — only the advertised public tools, never internal or admin routes — is served at:

• https://firm.tengu.co/api/openapi.json (no key needed to fetch the spec)

Load it into Swagger UI, Redoc, or Postman, or lint it:

npx @redocly/cli lint https://firm.tengu.co/api/openapi.json

SDKs#

Published, ready-to-install clients for both languages — same auth, same wallet, same tier gating:

1pip install tengu-firm      # Python  (import as: import tengu_firm)2npm i tengu-firm            # TypeScript / JavaScript

Prefer to generate the client yourself, or pin it to the live spec? Codegen either language:

1# Python2openapi-generator generate -i https://firm.tengu.co/api/openapi.json \3  -g python -o tengu-python --additional-properties=packageName=tengu_firm,projectName=tengu-firm4 5# TypeScript6openapi-generator generate -i https://firm.tengu.co/api/openapi.json \7  -g typescript-axios -o tengu-ts

No SDK required to start — the API is plain HTTP + JSON, so any client works:

1import requests2 3r = requests.get(4    "https://firm.tengu.co/api/v3/credit/bonds/F",5    headers={"Authorization": "Bearer tengu_YOUR_KEY"},6)7print(r.json()["rows"][:3])

For Claude Code & AI agents#

Two rules matter more than the rest when an agent drives this API:

1. Disambiguate colliding tickers. Nine symbols are both a crypto asset and a US-listed equity — BTC, ETH, LINK, LTC, COMP, ARB, NEAR, APT, ATOM. On score and ml_prediction tools, pass asset_class=equity or asset_class=crypto explicitly. Responses for those nine carry a ticker_collision note that must be relayed to the user — presenting the equity BTC as Bitcoin is a correctness failure. Requesting the crypto side fails closed with 404 crypto_model_unavailable; that never means "fall back to the equity." Full detail in Ticker collisions.

2. Streams are long-lived, not request/response. The /stream/* tools return Server-Sent Events and stay open. Outside roughly 04:00–20:00 ET they emit heartbeats and no market data — that is correct, not a failure. Don't retry a quiet stream. See Real-Time Streaming.

Beyond that: read /api/capabilities before generating calls rather than guessing paths, retry only 429 and 502, and check X-Credits-Cost / X-Credits-Remaining on each response to track spend.