// developers · mcp

One endpoint for any MCP client.

Point Claude, or any client that speaks the Model Context Protocol, at https://app.magistry.io/api/mcp. It signs in with OAuth and sees exactly the tools its grant allows.

// connect

Claude Code in one command.

claude code

claude mcp add --transport http magistry https://app.magistry.io/api/mcp

The first call answers 401 with a WWW-Authenticate header pointing at the protected-resource metadata, so the client finds the authorization server, opens the sign-in page and stores the token itself. In Claude.ai and Claude Desktop, add the same URL as a custom connector.

// revisions

Both protocol revisions, on the same URL.

2026-07-28 · stateless

No initialize handshake and no session. Every request carries its protocol version and client capabilities in params._meta, so any request can land on any server.

The optional Mcp-Method and Mcp-Name headers let a gateway route without reading the body. If they disagree with the body, the request is refused with JSON-RPC error -32020.

2025-06-18 · initialize

The earlier revision: initialize first, then tools/list and tools/call. Existing clients keep working without changes.

// raw json-rpc

What a client actually sends.

Useful when you are writing your own client or debugging one. The same API key or OAuth token works on MCP and REST.

2026-07-28 · tools/list

curl -X POST https://app.magistry.io/api/mcp \
  -H "Authorization: Bearer mag_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list",
        "params": { "_meta": {
          "io.modelcontextprotocol/protocolVersion": "2026-07-28",
          "io.modelcontextprotocol/clientCapabilities": {} } } }'

2026-07-28 · tools/call

curl -X POST https://app.magistry.io/api/mcp \
  -H "Authorization: Bearer mag_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: get_store_overview" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": { "name": "get_store_overview", "arguments": {},
          "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientCapabilities": {} } } }'

2025-06-18 · initialize

curl -X POST https://app.magistry.io/api/mcp \
  -H "Authorization: Bearer mag_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": { "protocolVersion": "2025-06-18", "capabilities": {},
          "clientInfo": { "name": "my-agent", "version": "1.0.0" } } }'

// what the client sees

Tools follow the grant.

Tools offered: The tools the token's scopes reach. Intent operations are listed to OAuth apps, finance reads to a finance:read grant
Read tools: Answer immediately and change nothing
Automatic writes: Apply when the grant includes write access
Proposed writes: Return an approval card; nothing changes until a person approves it in Magistry
Audit: Every message, including tools/list, is written to the audit log before the response returns

Build on the same tools the product uses.

Create a sandbox key on demo data, or start free and connect a real store.

Start free

Read the OpenAPI document

MCP + REST · OAuth 2.1 or API keys · every call audited