Skip to main content

AI Agent Access via Gateway MCP

Give an AI client (Cursor, Claude Desktop, or any MCP-compatible tool) the ability to discover and call your published APIs — using the same client, profile, and rate limit controls as your REST applications. No separate AI gateway; one audit trail for everything.

Typical scenario: Your team uses Cursor as a coding assistant. You want it to be able to call your internal orders-api to fetch live order data during development, under the same rate limit and access controls as your other clients.

How it works​

Zerq exposes a Gateway MCP endpoint (by default at /mcp) that speaks the Model Context Protocol over Streamable HTTP. When an AI client connects, it can:

  1. List collections — discover what API collections are published
  2. List endpoints — see proxies within a collection
  3. Get endpoint details — read path, method, parameters, and schema
  4. Execute a call — make a real API request through the gateway

Every execute call goes through the same gateway engine: authentication, profile checks, rate limiting, and full request logging.

Prerequisites​

  • You are signed in to the Management UI as an admin or editor
  • At least one published collection and proxy exist
  • The gateway is running and accessible (e.g. https://api.example.com)
  • You have Cursor, Claude Desktop, or another MCP-compatible client installed

Step 1 — Create a dedicated client for the AI agent​

Always use a dedicated client for AI/agent access — not shared credentials from a human user or existing system integration.

  1. Open Clients & Profiles → Clients, click New client.
  2. Set:
    • Name: ai-cursor-dev
    • Description: Cursor IDE integration for development environment
    • Status: Enabled
  3. Save. Note the Client ID.

Step 2 — Create a profile with minimal scope​

Least-privilege is critical for AI agent access. Grant only the methods and rate limits the agent needs.

  1. Open Clients & Profiles → Profiles, click New profile.
  2. Set:
    • Name: profile-cursor-dev
    • Client: ai-cursor-dev
    • Auth method: Token
  3. Generate a bearer token. Store it securely.
  4. Under Allowed methods: enable only GET (if the agent only reads data).
  5. Under Policy: attach a conservative policy, e.g. tier-dev-100rpm.
  6. Save.

Step 3 — Assign the agent client to collections​

Grant the agent access to the specific collections it needs.

  1. Open each collection the agent should access (e.g. orders-api).
  2. Under the Access tab, add ai-cursor-dev.
  3. Save. Repeat for each collection.

The agent will only see collections it has been granted access to when it calls list_collections.

Step 4 — Configure the MCP client​

Cursor​

In Cursor, open Settings → MCP Servers and add a new server:

{
  "mcpServers": {
    "zerq-orders-api": {
      "url": "https://api.example.com/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <your-bearer-token>",
        "X-Client-ID": "ai-cursor-dev",
        "X-Profile-ID": "profile-cursor-dev"
      }
    }
  }
}

Replace <your-bearer-token> with the token from step 2. Do not commit this token to version control.

Claude Desktop​

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zerq-orders-api": {
      "type": "streamableHttp",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-bearer-token>",
        "X-Client-ID": "ai-cursor-dev",
        "X-Profile-ID": "profile-cursor-dev"
      }
    }
  }
}

ChatGPT / custom MCP client​

Use the same JSON-RPC over HTTP pattern. Send these headers on every request:

  • Authorization: Bearer <token>
  • X-Client-ID: ai-cursor-dev
  • X-Profile-ID: profile-cursor-dev
  • Mcp-Session-Id: <session-id> (after initialize)

Step 5 — Initialize the MCP session​

The first call to the MCP endpoint must be an initialize handshake:

curl -i https://api.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "X-Client-ID: ai-cursor-dev" \
  -H "X-Profile-ID: profile-cursor-dev" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": { "tools": {} },
      "clientInfo": { "name": "cursor", "version": "1.0" }
    }
  }'

The response includes a Mcp-Session-Id header. Save this value — use it as Mcp-Session-Id on subsequent calls.

Step 6 — Verify the agent can discover and call APIs​

List available collections:

curl -s https://api.example.com/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "X-Client-ID: ai-cursor-dev" \
  -H "X-Profile-ID: profile-cursor-dev" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_collections","arguments":{}}}' | jq

Expected: a list of collections the client has access to (e.g. orders-api).

Execute an API call through the agent:

curl -s https://api.example.com/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "X-Client-ID: ai-cursor-dev" \
  -H "X-Profile-ID: profile-cursor-dev" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "execute_endpoint",
      "arguments": {
        "collectionId": "orders-api",
        "proxyId": "get-order",
        "pathParams": { "orderId": "ORD-9182" }
      }
    }
  }' | jq

Expected: the same 200 response the REST client would receive, subject to the same rate limits and profile restrictions.

Verify in observability​

Open Logs → Request Logs and filter by Client ID = ai-cursor-dev. You should see:

  • MCP tool calls (tools/list, tools/call)
  • Executed upstream calls with status, latency, and headers

Open Logs → Audit Logs to see the client and profile creation events, and confirm all agent activity is recorded.

Security checklist​

CheckAction
Dedicated clientUse ai-cursor-dev only for this integration
Minimal method scopeGET only unless the agent needs mutations
Conservative rate limitStart with 100 req/min and increase only if needed
Token rotationRotate the bearer token regularly or use short-lived JWT
Never commit tokensUse environment variables or a secrets manager

Next steps​