Home Developers MCP

CalculatorX Developers

Remote MCP

Three tools. One catalog. Pin calculation_version when the result must stay reproducible.

Try it

POST https://www.calculatorx.com/mcp
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
Mcp-Name: -

Canonical 2026-07-28 request: protocol headers plus JSON _meta. Official MCP SDKs populate _meta automatically. CalculatorX still accepts header-only curl without _meta.

Same-origin MCP for agents. One calculation layer for REST, MCP, and human-verifiable results. Hosted at /mcp — no separate worker.

Agent usage contract (when to call, how to read results, trust boundaries): For AI agents.

Purpose Endpoint
MCP RPC POST https://www.calculatorx.com/mcp
Human / simple discovery GET /mcp (server info + tool names; not the protocol handshake)
Protocol discovery POST /mcp · server/discover (2026-07-28)
Capability catalog /.well-known/calculatorx-capabilities.json
Agent usage contract For AI agents
Compatibility /.well-known/mcp-compatibility.json

GET /mcp is convenience metadata for browsers and simple HTTP clients. MCP clients should discover over POST /mcp: server/discover on 2026-07-28, or initialize on legacy 2024-11-05.

Do not load every calculator as its own MCP tool. Search the catalog, inspect a capability_id, then execute.

Tools

Four tools. The default agent path is still search → inspect → execute (free). compute_paid is the Stage 0.5 opt-in paid path and does not live-charge.

  1. search_capabilities — { query?, trust_level?, limit? }
  2. inspect_capability — { capability_id } (includes free commerce discovery)
  3. execute_calculation — { capability_id, inputs, calculation_version? } (stays free)
  4. compute_paid — { capability_id, inputs, payment?, quote_id?, idempotency_key? } — without payment returns PAYMENT_REQUIRED; REST equivalent is POST /api/v1/commerce/compute (HTTP 402)

execute_calculation covers the capability catalog, including education, units, and the full math hub (math.multiplication, math.sum, trig, logs, percentages, …). Registry engines such as gpa stay on REST until they are promoted.

Protocols

CalculatorX serves Streamable HTTP on a single /mcp endpoint. Protocol versions:

Protocol Notes
2026-07-28 Preferred. Stateless; send MCP-Protocol-Version, Mcp-Method, Mcp-Name; use server/discover. Canonical JSON-RPC also carries per-request _meta (protocolVersion, clientCapabilities, clientInfo).
2024-11-05 Legacy initialize / tools/* flow for older clients, on the same /mcp endpoint. This is not the 2024-11-05 HTTP+SSE dual-endpoint transport.

Prefer 2026-07-28. Official MCP SDKs populate the modern _meta envelope automatically. CalculatorX still accepts header-only curl without JSON _meta. Legacy clients may omit the new headers and use initialize / tools/* under 2024-11-05.

Examples

# Discover (2026-07-28 canonical)
curl -sS -X POST 'https://www.calculatorx.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  -H 'Mcp-Name: -' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"calculatorx-docs-example","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

# List tools
curl -sS -X POST 'https://www.calculatorx.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -H 'Mcp-Name: -' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"calculatorx-docs-example","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

# Execute (apparent power)
curl -sS -X POST 'https://www.calculatorx.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: execute_calculation' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_calculation","arguments":{"capability_id":"electrical.apparent_power","inputs":{"mode":"amps-va","primary":12,"volts":230,"phase":"single"},"calculation_version":"1.4.3"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"calculatorx-docs-example","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

Pin calculation_version (or CalculatorX-Spec-Version) so agents do not silently pick up formula changes. Mismatch returns HTTP 409 with code: "VERSION_MISMATCH".

Rate limits

Per IP, sliding window: MCP RPC ~120/min, execute_calculation ~30/min, REST POST /api/v1/calc/* ~60/min. Exceeded → HTTP 429 with code: "RATE_LIMITED" and Retry-After. Details: Errors.

Prefer capabilities with CVP Verified status and CURRENT production attestation (see CVP and capability Trust). Review-policy catalog tiers (engine_tested, internally_reviewed, expert_verified) remain available as supplemental filters — catalog token verified is L3 only. candidate means schemas exist but engine evidence is incomplete.