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}]"
      }
    ]
  }
}

Tools that require human approval

An org admin can flag any tool as requires approval (see Tool Approvals). When an agent calls a flagged tool, it is not executed immediately — it is held for a human to approve or reject. The tools/call response is a normal MCP result whose structuredContent marks it pending:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "This tool call requires human approval. It is now pending. Poll check_approval_status with approvalId \"appr-1a2b3c\"."
      }
    ],
    "structuredContent": { "status": "pending_approval", "approvalId": "appr-1a2b3c" },
    "isError": false
  }
}

Read approvalId from structuredContent, then poll the always-available check_approval_status tool until the call resolves:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "check_approval_status",
    "arguments": { "approvalId": "appr-1a2b3c" }
  }
}

The result’s structuredContent.status is one of pending, executed (with the tool result), rejected, expired, failed, or not_found. Once executed, the tool ran with the approved arguments and the result is returned to you. Unflagged tools are unaffected — they execute immediately as shown above.

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 quota exceeded. Upgrade your plan to continue."
  }
}

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

Skills Webhooks