Repository Public Research preview
1# claude-api-mcp23An MCP server for building with the Claude API. It gives an agent two things:451. **Knowledge that was measured, not remembered.** Model rules changed a lot between generations6 (thinking modes, effort levels, forced tool choice, prefill, sampling parameters). This server7 ships a knowledge base built by sending 46 request shapes to each of 15 models and recording8 what the API accepted. A linter turns that into findings and fixes before a request is sent.92. **Hands on the API.** Messages, token counting, structured extraction, batches, files and10 Managed Agents, with a spend guard, lint-before-send and confirmation on destructive calls.1112Not affiliated with Anthropic. "Claude" is a trademark of Anthropic, PBC.1314## Install1516Requires Node.js 20 or newer.1718```bash19skills download @spboucher/claude-api-mcp --extract ./claude-api-mcp # or download the archive and verify its SHA-25620cd claude-api-mcp21npm ci # installs @anthropic-ai/sdk, @modelcontextprotocol/sdk and zod from the lockfile22npm test # offline tests, no key needed23```2425Register it (use the absolute path of `server.mjs`):2627```bash28# Claude Code29claude mcp add --transport stdio --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude-api -- node /abs/path/claude-api-mcp/server.mjs30```3132```toml33# Codex: ~/.codex/config.toml34[mcp_servers.claude-api]35command = "node"36args = ["/abs/path/claude-api-mcp/server.mjs"]37env_vars = ["ANTHROPIC_API_KEY"]38```3940```json41// Cursor: .cursor/mcp.json42{ "mcpServers": { "claude-api": { "type": "stdio", "command": "node", "args": ["/abs/path/claude-api-mcp/server.mjs"], "env": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" } } } }43```4445The key is optional: the ten offline tools work without it.4647| Variable | Purpose | Default |48|---|---|---|49| `ANTHROPIC_API_KEY` | Key for the live tools. Read from the environment, never returned in any output | none |50| `CLAUDE_API_MCP_MAX_OUTPUT_TOKENS` | Spend guard: largest `max_tokens` the server will send | 32000 |51| `CLAUDE_API_MCP_FILE_ROOT` | Only directory `file_upload` may read from | working directory |5253## Tools5455**Offline (no key, no cost)**5657| Tool | What it does |58|---|---|59| `model_reference` | Context window, output cap, prices, thinking modes, effort levels, forced tool choice, prefill, sampling, betas, server tools — per model or as a table |60| `recommend_model` | Model and effort for a task, honouring hard requirements |61| `lint_request` | Findings for a Messages request, each with a fix and the API error text observed |62| `fix_request` | Applies the mechanical fixes and reports what changed |63| `migrate_request` | Rewrites a request for another model and lists what to review |64| `estimate_cost`, `compare_costs` | Cost with cache reads/writes, batch discount, fast mode, long-prompt rates |65| `scaffold_agent` | Runnable starters: single call, streaming, structured output, manual tool loop, tool runner, batch, Managed Agent — TypeScript or Python |66| `explain_error` | Maps a status or message to a cause and a fix |67| `feature_guide` | Short guidance on 15 topics |6869**Live**7071| Tool | Notes |72|---|---|73| `list_models`, `get_model`, `count_tokens` | Free |74| `create_message` | Billed. Linted first; nothing is sent if the API would reject it. `auto_fix` applies fixes. Betas go in `request.betas` |75| `extract_structured` | Billed. Returns parsed JSON matching your schema |76| `batch_create`, `batch_get`, `batch_list`, `batch_results`, `batch_cancel` | Half price; results keyed by `custom_id` |77| `file_upload`, `file_list`, `file_get`, `file_delete` | Uploads are confined to the file root |78| `agent_*`, `environment_*`, `session_*` | Managed Agents (beta). `session_run` never approves a tool call by itself |7980Destructive tools (`file_delete`, `batch_cancel`, `*_archive`) refuse to act without `confirm: true`.8182## What "verified" means here8384- `probes/probe.mjs` and `probes/probe2.mjs` send small requests to every model the key can see.85 Raw results: `probes/matrix.json`, `probes/matrix2.json`. `probes/build-knowledge.mjs` derives86 `knowledge.json` from them. Prices come from the official pricing page (read 2026-11-10 UTC).87- `test/offline.test.mjs` asserts that the linter predicts accept/reject **exactly** as the API did88 for every recorded outcome (30 shapes × 15 models), and that the fixer yields acceptable requests.89- `test/run-scaffolds.mjs` executes every scaffold template against the API in both languages.90- `test/live.test.mjs` drives the server through the MCP protocol with the official client:91 messages, tools, vision, PDF, citations, caching, web search, betas, files, batches, Managed Agents.9293Refresh the knowledge base yourself: `ANTHROPIC_API_KEY=… npm run probe` (costs a few cents to a94few dollars depending on the models your key can see), then `npm test`.9596## Limits — read these9798- **A snapshot.** Behaviour was observed on 2026-11-10 (UTC) under API version `2026-10-21` (the SDK99 default) with two legacy probes under `2023-06-01`. APIs change; `model_reference` reports the100 observation date. Re-run the probes when in doubt.101- **Only models the probing key could see.** Mythos models and any model released later are absent;102 the linter reports them as unknown rather than guessing.103- **Not probed:** computer use, the advisor tool, memory stores, message threads, preserved-thinking104 replay rules, Bedrock / Vertex / Foundry differences. The linter is silent on these.105- **Cost figures are estimates** from list prices; server-tool charges are not included. Check106 `response.usage` and your invoice.107- `recommend_model` is a heuristic. Evaluate on your own data.108- Model output returned by tools is untrusted text. Do not let it trigger actions unreviewed.109110## Security111112The server reads the key from its environment and scrubs key-shaped strings from error messages.113It executes no model output, opens no listening port, and reads local files only for `file_upload`114inside the configured root. Managed Agent tool calls that need approval are surfaced, never115auto-approved.116