Tools

MCP — agents and IDEs

Connect Claude Code, Cursor, or any MCP client to ARCNM over HTTP with a bearer token.

ARCNM ships a Model Context Protocol server, auto-generated from the REST API. MCP-speaking agents and IDEs can quote parts, inspect calculations, and read your data through typed tools — without you writing glue code.

Endpoint: https://api.arcnm.io/mcp-server/mcp (HTTP transport, bearer-JWT protected).

Why MCP, not REST

If you're writing application code, use REST. Pick MCP when an agent is the client (Claude, Cursor, custom runtimes): it discovers tools automatically and routes arguments through structured schemas.

Authentication

The MCP server is a bearer-token protected resource. It publishes RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource. The verifier accepts either credential in the Authorization: Bearer … header:

an ARCNM API key (ak_live_… / ak_test_…) — recommended for agents: long-lived, revocable, scoped (tried first); or
a tenant-scoped session access token (JWT, audience-pinned to /api/v1; refresh tokens and other-audience tokens are rejected).

There is no browser consent flow yet — you supply the credential to your client explicitly. Mint an API key in the dashboard (Settings → API keys) and pass it as the bearer token.

Connect

Claude Code (CLI)

claude mcp add -t http arcnm https://api.arcnm.io/mcp-server/mcp \
  --header "Authorization: Bearer $ARCNM_MCP_TOKEN"

Cursor

Add to ~/.cursor/mcp.json (or project-scoped .cursor/mcp.json):

{
  "mcpServers": {
    "arcnm": {
      "transport": {
        "type": "http",
        "url": "https://api.arcnm.io/mcp-server/mcp",
        "headers": { "Authorization": "Bearer ${ARCNM_MCP_TOKEN}" }
      }
    }
  }
}

Restart Cursor; tools appear under the MCP picker.

Other clients

Any MCP-compliant HTTP client works. Point the transport at https://api.arcnm.io/mcp-server/mcp, send the bearer header, and call the standard tools/list / resources/list methods to discover the surface.

What's exposed

Tools and resources are derived from the REST API and filtered through an explicit allow-list:

GET endpoints (parts, calculations, environments, your own identity) appear as MCP resources / resource-templates.
Write endpoints (create a part, create/run/quote a calculation, upload inputs) appear as MCP tools.

Tool and resource names are generated from the REST operation ids (roughly <tag>_<operation>, e.g. a calculation create/quote/run tool under the parts tag). The authoritative list is whatever tools/list returns for your token — generate it from the live server rather than hardcoding names.

What's never exposed. Wallet and billing operations, plan changes, member invites/roster, API-key minting, the credential vault, SSO/SCIM, raw payment-provider webhooks, feature flags, auth/session primitives, and user create/delete/password changes. An agent with a tenant token cannot move money, escalate access, mint credentials, or rewrite the tenant — those stay human-dashboard-only by design.

Scopes mirror the REST scope catalog: a token needs parts:read to read and parts:write to create or run a calculation. Request the minimum the agent needs.

Tool annotations

Each tool carries MCP annotations the agent uses to decide how to call it:

openWorldHint is set on tools.
idempotentHint is false for POST / PATCH, true for PUT.
destructiveHint and idempotentHint are true for DELETE.

A well-behaved agent confirms with the user before calling a destructiveHint tool.

Worked example — agent quotes a part

user: Quote this STEP file at lot size 50, on our production env.
      [attaches bracket.step]

agent: <calls the parts upload-and-quote tool>
       cad_file=<bytes>, part_number="BRACKET-001",
       lot_size=50, costing_environment_id=<prod env id>

agent: ← { id: "9d…", status: "queued" }

agent: <polls the get-calculation resource for 9d… until status=succeeded>

agent: Unit cost at lot size 50 is €12.84 (total €642.00, setup €52.50).
       The full breakdown is on the calculation's analytics blob.

The agent didn't write a line of REST glue.

Rate limits & billing

MCP traffic is handled by the MCP server's own verification and is not subject to the REST per-request quota bucket. You're billed for the underlying billable operation (a successful calculation), not per tool call — read-only tools and resources are free.

Local development

Run a local backend and point your MCP client at http://localhost:8000/mcp-server/mcp with a dev bearer token — an ak_test_… API key works well locally. The MCP transport reads the Authorization: Bearer header only (an API key or a session JWT); there is no X-API-Key header path on the MCP server — that header is REST-only.