MCP Server

Endpoint & Transport

The portal serves the MCP surface directly as a first-class API namespace over the MCP Streamable HTTP transport. There is nothing to install: the server that used to ship as the standalone satsrail-mcp npm package now lives in the API itself, so tools never drift from the endpoints they call.

Authentication

Every request carries a standard SatsRail API token in the Authorization header — the same keys the rest of the merchant API uses. The token is forwarded to each underlying API call, so merchant scope, security groups, and rate limits are enforced exactly as they are for REST.

Authorization: Bearer sk_live_your_key

A missing or invalid token returns HTTP 401 with JSON-RPC error -32001. Create keys in your dashboard — the API tokens page also renders a ready-to-paste "Connect an AI assistant (MCP)" config card with your token pre-filled. There is no OAuth flow today; the bearer header is the only credential.

Connect Your Client

Modern MCP clients connect to a remote server with a URL and a header. Pick your client below. Stdio-only clients bridge through mcp-remote.

• Claude Code
• Claude Desktop
• Cursor
• Windsurf
• Stdio bridge

claude mcp add --transport http satsrail https://satsrail.com/api/v1/mcp \
  --header "Authorization: Bearer sk_test_your_key"

{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key" }
    }
  }
}

{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key" }
    }
  }
}

{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key" }
    }
  }
}

{
  "mcpServers": {
    "satsrail": {
      "command": "npx",
      "args": ["mcp-remote", "https://satsrail.com/api/v1/mcp",
               "--header", "Authorization: Bearer sk_live_your_key"]
    }
  }
}

Protocol Methods

Example — tools/call

Request:

curl -X POST https://satsrail.com/api/v1/mcp \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_order",
      "arguments": {
        "total_amount_cents": 2500,
        "currency": "usd",
        "generate_invoice": true
      }
    }
  }'

Response (abridged):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ \"id\": \"...\", \"status\": \"pending\", \"invoice\": { \"bolt11\": \"lnbc250u1p...\" } }" }],
    "isError": false
  }
}

Tool Catalog

45 tools cover the full merchant surface. All target the /m/ merchant namespace except list_subscription_plans, which is public. Tools marked pk_ also work with publishable keys.

Orders & invoices (9)

Payments, checkout & payment requests (8)

Products & catalog (15)

Webhooks (5)

Merchant & account (6)

Access & public (2)

Errors, Rate Limits & Auditing

Protocol-level problems return JSON-RPC errors. Failures from the underlying API surface as tool results with isError: true carrying the API's error message — they do not break the protocol stream.

Rate limiting: a JSON-RPC request is charged once against your plan's API limits, not once per tool — the MCP layer dispatches in-process below the throttle. Monitor usage with get_api_token_usage. Auditing: every tools/call is logged (tool name, token, merchant, success) — arguments and results are never stored. Protocol chatter like initialize and tools/list is not logged.

Quick Test

Confirm the connection and count the tools:

curl -s https://satsrail.com/api/v1/mcp \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'
# => 45