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 accepts query, verification_status, production_freshness, profile, trust_level, tier, and limit.
  2. inspect_capability requires capability_id and accepts the same three CVP filters, plus operation and detail_level. It also 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.

CVP discovery

To find a verified unit conversion with a current production attestation, call search_capabilities with these arguments.

{
  "query": "metre to feet length conversion",
  "verification_status": "VERIFIED",
  "production_freshness": "CURRENT",
  "profile": "engineering"
}

The filters are optional, exact and combined with AND. Search applies them before the result limit. Inspect returns CVP_FILTER_MISMATCH when the requested capability fails a filter. The CVP fields are available in search results and in both inspect detail levels. For a matching Manifest, the result includes a pinned cvp_manifest link and any published verification_revision and cvp_core_sha256.

verification_status describes the verification suite. production_freshness describes the production binding, so a result can be VERIFIED and STALE. If the discovery data is unavailable, the CVP fields are null and CVP filters return no match. The Review policy filters trust_level and tier remain available for existing clients.

For units.convert, these fields apply to the capability and its pinned unit registry. Use the Manifest to check the scope of the specific unit pair and choose stable IDs when discovery reports ambiguous candidates.

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.

Raw HTTP clients should send an application-specific User-Agent identifying the client and its version. The default Python urllib identifier can receive an HTTP 403 with edge error 1010 before the request reaches MCP. Treat that as an access error. A calculation rejection is returned in the MCP tool result with isError: true and a structured error code.

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.