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. execute_calculation also accepts the calculationVersion argument alias. All supplied pins, including fields inside inputs, must agree: conflicts return VERSION_PIN_CONFLICT, and empty or wrongly typed pins return INVALID_VERSION_PIN. A lone old pin returns VERSION_MISMATCH. MCP reports calculation errors in the final tool result with isError: true and the underlying http_status; the JSON-RPC transport may still return HTTP 200. Do not remove an intentional version lock when retrying.

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.