MCP Protocol

ApexMCP implements the Model Context Protocol over HTTP using JSON-RPC 2.0.

Endpoint

POST https://gateway.apexmcp.ai/mcp/:orgSlug

orgSlug — your organisation’s URL slug (set during sign-up)
Content-Type: application/json required
Authentication header required (see Authentication)

JSON-RPC 2.0 Format

All requests follow standard JSON-RPC 2.0:

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

All responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

Or on error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

tools/list

Returns all tools the authenticated credential has access to.

Request:

curl -X POST https://gateway.apexmcp.ai/mcp/acme-corp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apx_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "query_postgres_orders",
        "description": "Query the orders table in PostgreSQL connector 'production-db'",
        "inputSchema": {
          "type": "object",
          "properties": {
            "sql": {
              "type": "string",
              "description": "SQL SELECT query. Only SELECT statements are permitted."
            },
            "limit": {
              "type": "integer",
              "description": "Maximum rows to return",
              "default": 100,
              "maximum": 1000
            }
          },
          "required": ["sql"]
        }
      }
    ]
  }
}

tools/call

Execute a tool. The arguments object must match the tool’s inputSchema.

Request:

curl -X POST https://gateway.apexmcp.ai/mcp/acme-corp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apx_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query_postgres_orders",
      "arguments": {
        "sql": "SELECT id, status, total FROM orders WHERE status = '\''pending'\'' LIMIT 50",
        "limit": 50
      }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\":101,\"status\":\"pending\",\"total\":299.99},{\"id\":102,\"status\":\"pending\",\"total\":49.00}]"
      }
    ]
  }
}

Error Codes

Code	Name	Description
`-32600`	Invalid Request	Malformed JSON-RPC request
`-32601`	Method Not Found	Unknown method (not `tools/list` or `tools/call`)
`-32602`	Invalid Params	Arguments don’t match tool’s `inputSchema`
`-32000`	Quota Exceeded	Monthly tool call quota reached for your plan
`-32003`	Insufficient Scope	Credential lacks permission to call this tool

Rate Limiting

ApexMCP enforces two layers of limits:

Burst limit (per second)

If a single client exceeds the per-second burst threshold, the gateway returns:

HTTP 429 Too Many Requests
Retry-After: 1

Back off for at least 1 second and retry.

Monthly quota

When the monthly tool call quota for your plan is exhausted, every tools/call returns a JSON-RPC error:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "api_limit_reached: monthly quota exhausted. Upgrade your plan at apexmcp.ai/pricing"
  }
}

tools/list calls do not count against quota.

Plan limits

Plan	Monthly tool calls	Burst
Starter	20,000	20/s
Growth	50,000	50/s
Scale	Unlimited	100/s
Enterprise	Unlimited	Custom
Standalone	Unlimited	Custom

External MCP Connector Webhooks