Skip to main content

MCP Gateway

The Gateway MCP surface exposes your published API endpoints as MCP tools. AI agents and coding assistants can discover your APIs and make real gateway calls using the same authentication, rate limits, and audit trail as regular REST requests.

This is the MCP surface for API consumers — it's how AI tools interact with APIs you've published. The Developer Portal can expose the same tools through Zerq Copilot for Gateway when LLM settings are enabled. For AI tools that need to manage the platform (create collections, configure proxies), see Management MCP.

How it works​

The Gateway MCP runs on the same path as your gateway (default /mcp), uses JSON-RPC over streamable HTTP, and requires the same X-Client-ID/X-Profile-ID headers as any other gateway request.

The 4 MCP tools​

ToolWhat it does
list_collectionsReturns all active collections the client has access to, including published_endpoints count per collection
list_endpointsReturns a flat list of all published proxies: endpoint_id, collection_name, name, description, path, methods
endpoint_detailsReturns full detail for one endpoint: path_params, query_params, request_example, response_example, request_schema, response_schema
execute_endpointExecutes a real gateway request using the client's auth; subject to rate limits, logging, and RBAC; returns isError: true on 4xx/5xx responses

Quickstart — first MCP call​

1. Initialize a session​

curl -X POST "https://gateway.example.com/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456" \
  -H "Authorization: Bearer zerq_tok_xxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": 1,
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

The response includes an Mcp-Session-Id header — include this in all subsequent requests.

2. List available tools​

curl -X POST "https://gateway.example.com/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456" \
  -H "Authorization: Bearer zerq_tok_xxxxxx" \
  -H "Mcp-Session-Id: <session-id-from-step-1>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

3. Execute an endpoint​

curl -X POST "https://gateway.example.com/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456" \
  -H "Authorization: Bearer zerq_tok_xxxxxx" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 3,
    "params": {
      "name": "execute_endpoint",
      "arguments": {
        "collection_id": "coll_abc123",
        "endpoint_id": "ep_xyz789",
        "query_params": { "limit": 10 }
      }
    }
  }'

Session management​

  • The server returns an Mcp-Session-Id on initialize
  • All subsequent requests must include this header
  • A missing or invalid session ID returns 400 Bad Request
  • GET requests open a Server-Sent Events (SSE) stream — one stream per session

Security and limits​

  • Gateway MCP requests are subject to the same rate limits and quotas as REST requests
  • Every tool call creates a request log entry with the same metadata as a regular API call
  • The execute_endpoint tool has a 60-second timeout
  • Scope is limited to the collections the client profile has access to