API Reference

Base URL

Until the appliance has a domain it serves a self-signed certificate. curl needs --insecure for it, and MCP clients reject it: see Connect an MCP client.

Authentication

All requests require an API key passed in the Authorization header:

Authorization: Bearer axgw_live_k1_your_key_here

Create API keys in your appliance's console (https://<your-appliance-host>) under API Keys (in the General section of the sidebar).

MCP Endpoint

The main MCP protocol endpoint. Send JSON-RPC 2.0 requests to interact with your connected servers. Tool names are <alias>__<tool> here. Two other endpoints serve the same gateway: /mcp/<alias> exposes a single server with its own, un-prefixed tool names, and /mcp/sse is the older SSE transport for clients that do not speak Streamable HTTP.

Request Format

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": { /* optional parameters */ },
  "id": 1
}

Response Format

// Success
{
  "jsonrpc": "2.0",
  "result": { /* response data */ },
  "id": 1
}

// Error
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Error description"
  },
  "id": 1
}

Streamable HTTP Transport

The gateway implements MCP Streamable HTTP (spec 2025-03-26). Clients that support this transport (like OpenAI Codex) can connect directly. Clients that use stdio (like Claude Desktop) connect via the mcp-remote bridge.

Session Management

The initialize response includes an Mcp-Session-Id header. Clients should include this header in subsequent requests for session correlation. Sessions expire after 30 minutes of inactivity.

# Response header from initialize
Mcp-Session-Id: aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678

# Include in subsequent requests
Mcp-Session-Id: aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678

Notifications

JSON-RPC notifications (messages without an id field) return 202 Accepted with an empty body.

Batch Requests

Send a JSON array of messages to process multiple requests in a single HTTP call. The response is an array of results (notifications are excluded from the response).

Methods

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "github__get_me",
        "description": "Get the authenticated user",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "github__list_repos",
        "description": "List repositories",
        "inputSchema": {
          "type": "object",
          "properties": {
            "visibility": {
              "type": "string",
              "enum": ["all", "public", "private"]
            }
          }
        }
      }
    ]
  },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "github__get_me",
    "arguments": {}
  },
  "id": 2
}

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"login\":\"octocat\",\"id\":1,\"name\":\"The Octocat\"}"
      }
    ]
  },
  "id": 2
}

{
  "jsonrpc": "2.0",
  "method": "resources/list",
  "id": 3
}

{
  "jsonrpc": "2.0",
  "method": "prompts/list",
  "id": 4
}

Error Codes

Rate Limits

Each API key has a per-minute request limit, set when the key is created (the default is 1,000 requests per minute). The limit counts only requests that authenticate with an API key on the MCP routes (POST /mcp, POST /mcp/<alias>, DELETE /mcp and the SSE routes), one per HTTP request, so a JSON-RPC batch counts once. The console's own requests and the /api/* routes are not counted.

At the limit the gateway answers 429 with {"detail": "Rate limit exceeded"} and a Retry-After header (seconds until a request frees up). Requests that are refused are not counted, so a client that waits for Retry-After is let in again.

Other limits: your appliance can hold at most 10 API keys and 25 registered servers.

Requests under the limit carry rate limit headers (X-RateLimit-Reset is the Unix time, in seconds, at which the oldest counted request leaves the 60-second window):

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704067260