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 (40 of them), 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 ≥ 18) that forwards stdio JSON-RPC to the hosted /mcp endpoint. It ships no calculation logic, so it always stays in sync with the API. Add it to your client config (Claude Desktop claude_desktop_config.json, Cursor mcp.json):

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

NUMERATICA_API_KEY is required (the bridge exits with a clear message if it's unset); it's forwarded as a Bearer token and never logged. Don't have a key? Get a free one. 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, authenticated with your API key as a Bearer token (the same key + metering as REST):

{
  "mcpServers": {
    "numeratica": {
      "url": "https://api.numeratica.com/mcp",
      "headers": { "Authorization": "Bearer ${env:NUMERATICA_API_KEY}" }
    }
  }
}

Tool names

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

• /v1/retirement/monte-carlo → retirement_monte_carlo
• /v1/tax/estimate → tax_estimate
• /v1/medicare/irmaa → medicare_irmaa

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

Your key, kept safe

• The key is read from the environment and forwarded as a Bearer token — it is never logged.
• Never commit your key. Keep it in your shell or a secret manager and reference it via ${env:NUMERATICA_API_KEY} as above.
• MCP tool calls are authenticated and metered exactly like REST calls, so usage and rate limits apply the same way.

← All guides