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 ≥ 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