# claude-api-mcp

An MCP server for building with the Claude API. It gives an agent two things:

Knowledge that was measured, not remembered. Model rules changed a lot between generations (thinking modes, effort levels, forced tool choice, prefill, sampling parameters). This server ships a knowledge base built by sending 46 request shapes to each of 15 models and recording what the API accepted. A linter turns that into findings and fixes before a request is sent.
Hands on the API. Messages, token counting, structured extraction, batches, files and Managed Agents, with a spend guard, lint-before-send and confirmation on destructive calls.

Not affiliated with Anthropic. "Claude" is a trademark of Anthropic, PBC.

# Install

Requires Node.js 20 or newer.

bash

skills download @spboucher/claude-api-mcp --extract ./claude-api-mcp   # or download the archive and verify its SHA-256
cd claude-api-mcp
npm ci            # installs @anthropic-ai/sdk, @modelcontextprotocol/sdk and zod from the lockfile
npm test          # offline tests, no key needed

bash

# Claude Code
claude mcp add --transport stdio --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude-api -- node /abs/path/claude-api-mcp/server.mjs

toml

# Codex: ~/.codex/config.toml
[mcp_servers.claude-api]
command = "node"
args = ["/abs/path/claude-api-mcp/server.mjs"]
env_vars = ["ANTHROPIC_API_KEY"]

json

// Cursor: .cursor/mcp.json
{ "mcpServers": { "claude-api": { "type": "stdio", "command": "node", "args": ["/abs/path/claude-api-mcp/server.mjs"], "env": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" } } } }

The key is optional: the ten offline tools work without it.

Variable	Purpose	Default
`ANTHROPIC_API_KEY`	Key for the live tools. Read from the environment, never returned in any output	none
`CLAUDE_API_MCP_MAX_OUTPUT_TOKENS`	Spend guard: largest `max_tokens` the server will send	32000
`CLAUDE_API_MCP_FILE_ROOT`	Only directory `file_upload` may read from	working directory

# Tools

Offline (no key, no cost)

Tool	What it does
`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
`recommend_model`	Model and effort for a task, honouring hard requirements
`lint_request`	Findings for a Messages request, each with a fix and the API error text observed
`fix_request`	Applies the mechanical fixes and reports what changed
`migrate_request`	Rewrites a request for another model and lists what to review
`estimate_cost`, `compare_costs`	Cost with cache reads/writes, batch discount, fast mode, long-prompt rates
`scaffold_agent`	Runnable starters: single call, streaming, structured output, manual tool loop, tool runner, batch, Managed Agent — TypeScript or Python
`explain_error`	Maps a status or message to a cause and a fix
`feature_guide`	Short guidance on 15 topics

Live

Tool	Notes
`list_models`, `get_model`, `count_tokens`	Free
`create_message`	Billed. Linted first; nothing is sent if the API would reject it. `auto_fix` applies fixes. Betas go in `request.betas`
`extract_structured`	Billed. Returns parsed JSON matching your schema
`batch_create`, `batch_get`, `batch_list`, `batch_results`, `batch_cancel`	Half price; results keyed by `custom_id`
`file_upload`, `file_list`, `file_get`, `file_delete`	Uploads are confined to the file root
`agent_`, `environment_`, `session_*`	Managed Agents (beta). `session_run` never approves a tool call by itself

Destructive tools (file_delete, batch_cancel, *_archive) refuse to act without confirm: true.

# What "verified" means here

probes/probe.mjs and probes/probe2.mjs send small requests to every model the key can see. Raw results: probes/matrix.json, probes/matrix2.json. probes/build-knowledge.mjs derives knowledge.json from them. Prices come from the official pricing page (read 2026-11-10 UTC).
test/offline.test.mjs asserts that the linter predicts accept/reject exactly as the API did for every recorded outcome (30 shapes × 15 models), and that the fixer yields acceptable requests.
test/run-scaffolds.mjs executes every scaffold template against the API in both languages.
test/live.test.mjs drives the server through the MCP protocol with the official client: messages, tools, vision, PDF, citations, caching, web search, betas, files, batches, Managed Agents.

Refresh the knowledge base yourself: ANTHROPIC_API_KEY=… npm run probe (costs a few cents to a few dollars depending on the models your key can see), then npm test.

# Limits — read these

A snapshot. Behaviour was observed on 2026-11-10 (UTC) under API version 2026-10-21 (the SDK default) with two legacy probes under 2023-06-01. APIs change; model_reference reports the observation date. Re-run the probes when in doubt.
Only models the probing key could see. Mythos models and any model released later are absent; the linter reports them as unknown rather than guessing.
Not probed: computer use, the advisor tool, memory stores, message threads, preserved-thinking replay rules, Bedrock / Vertex / Foundry differences. The linter is silent on these.
Cost figures are estimates from list prices; server-tool charges are not included. Check response.usage and your invoice.
recommend_model is a heuristic. Evaluate on your own data.
Model output returned by tools is untrusted text. Do not let it trigger actions unreviewed.

# Security

The server reads the key from its environment and scrubs key-shaped strings from error messages. It executes no model output, opens no listening port, and reads local files only for file_upload inside the configured root. Managed Agent tool calls that need approval are surfaced, never auto-approved.

spb llm-api-toolkits