Use Numeratica from an AI agent (MCP)

Let Claude Desktop, Cursor, Cline, or any MCP client run the calculators for you. The agent calls the math; you get the real numbers back — reproducible result_id and all.

Numeratica speaks the Model Context Protocol. Every /v1 endpoint is exposed as a tool (76 of them, plus batch), and each tool's input schema is generated from the API's request types, so the tools can't drift from what the API accepts. Results come back verbatim — the result_id, seed, and disclaimer are preserved, so reproducibility survives into the agent's context.

Option A · Easiest — npx @numeratica/mcp

For Claude Desktop, Cursor, or any stdio MCP client, use the open-source bridge @numeratica/mcp — a thin, zero-dependency npx package (Node ≥ 20) that forwards stdio JSON-RPC to the hosted /mcp endpoint. It ships no calculation logic, so it always stays in sync with the API.

Step 1 · Look around — no key, no signup

Add this to your client config (Claude Desktop claude_desktop_config.json, Cursor mcp.json) and restart. Every tool appears, and you can ask the agent what's available:

{
  "mcpServers": {
    "numeratica": {
      "command": "npx",
      "args": ["-y", "@numeratica/mcp"]
    }
  }
}

With no key the bridge runs in discovery-only mode: listing and inspecting tools works, and running a calculation returns a message telling you to add a key. That is the intended state, not a failure — the hosted endpoint answers initialize, tools/list and ping without credentials so you can see exactly what you would be signing up for.

Step 2 · Add a key to run calculations

Get a free key, then add one line:

{
  "mcpServers": {
    "numeratica": {
      "command": "npx",
      "args": ["-y", "@numeratica/mcp"],
      "env": { "NUMERATICA_API_KEY": "nmr_sk_..." }
    }
  }
}

The key is forwarded as a Bearer token and never logged. Source (MIT): github.com/numeratica/mcp.

Option B · Remote — hosted /mcp + Bearer

For clients that speak remote MCP, skip the bridge and point straight at the Streamable-HTTP transport at POST /mcp. Pass your API key as a Bearer token — running a tool needs it, and usage is metered against it exactly as REST is:

{
  "mcpServers": {
    "numeratica": {
      "url": "https://api.numeratica.com/mcp",
      "headers": { "Authorization": "Bearer ${env:NUMERATICA_API_KEY}" }
    }
  }
}
Some clients only do OAuth for remote MCP servers and won't send a static Bearer — for those, use the npx bridge above. (OAuth support is a later phase.)
Discovery works without a key. initialize, tools/list and ping answer unauthenticated, so any client or registry can enumerate the catalogue before you have signed up — the tool schemas are generated from the public OpenAPI spec and are not secret. tools/call is the part that needs a key: it runs the same authenticated, metered, rate-limited path as the REST endpoint behind it. Anonymous discovery is throttled per IP.

Tool names

A tool name is its endpoint path with /v1/ dropped and the remaining / and - turned into _:

The full set of tools mirrors the API Reference — one per endpoint.

Your key, kept safe

← All guides