MCP integration

BuildCalc API mounts a Model Context Protocol (MCP) server at https://api.buildcalcapi.dev/mcp exposing all 79 calculators + the list_calculators discovery tool as MCP tools auto-generated from the OpenAPI schema (powered by fastapi_mcp).

Protocol

Transport: Streamable HTTP (MCP spec 2025-03-26)
Authentication: Bearer token in Authorization header (same key as REST)
Tool naming: calc_<category>_<kind> (e.g., calc_concrete_yards, calc_electrical_panel_load) plus list_calculators
80 tools total: 79 calc + 1 discovery

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "buildcalc": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.buildcalcapi.dev/mcp",
        "--header",
        "Authorization:Bearer bcapi_..."
      ]
    }
  }
}

Restart Claude Desktop. The tools panel should show the BuildCalc tools.

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "buildcalc": {
      "url": "https://api.buildcalcapi.dev/mcp",
      "headers": {
        "Authorization": "Bearer bcapi_..."
      }
    }
  }
}

Custom MCP client (raw protocol)

# 1. initialize — captures Mcp-Session-Id header
curl -i -X POST https://api.buildcalcapi.dev/mcp \
  -H "Authorization: Bearer bcapi_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-agent", "version": "1.0"}
    }
  }'
# Returns: Mcp-Session-Id: <session>

# 2. tools/list — uses the session header
curl -X POST https://api.buildcalcapi.dev/mcp \
  -H "Authorization: Bearer bcapi_..." \
  -H "Mcp-Session-Id: <session>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. tools/call
curl -X POST https://api.buildcalcapi.dev/mcp \
  -H "Authorization: Bearer bcapi_..." \
  -H "Mcp-Session-Id: <session>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 3,
    "method": "tools/call",
    "params": {
      "name": "calc_concrete_yards",
      "arguments": {"length_ft": 10, "width_ft": 10, "depth_in": 4}
    }
  }'

Auth + rate limiting at the MCP layer

The Bearer token is validated:

At the MCP transport (prevents unauthenticated tool discovery)
At the underlying REST endpoint when each tool invocation runs (so per-key rate limits + usage metering work identically for REST and MCP)

Tools that don't carry a calc:* or data:* tag (signup, billing, admin endpoints) are not exposed via MCP — they require explicit HTTP REST access.

Tool description quality

Every tool's MCP description is the FastAPI route summary + Pydantic input/output schema, derived from the OpenAPI spec. AI agents have full schema visibility for input validation client-side and structured-output expectations.

Discovery

Call list_calculators first if your agent prefers structured exploration:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {"name": "list_calculators", "arguments": {}}
}

Returns categories with {kind, path, summary} per calc.