Skip to main content

Cursor Setup

Use this guide to connect Cursor to Zerq MCP endpoints for runtime API calls (Gateway MCP) and optional platform automation (Management MCP).

1) Decide which MCP surface to connect​

  • Gateway MCP: for agent calls to published APIs under client/profile controls.
  • Management MCP: for operator automations (collections/proxies/workflows/policies) with OIDC RBAC.

2) Configure MCP server entry in Cursor​

In Cursor MCP settings, add a server that points to your deployed endpoint:

  • Gateway MCP URL example: https://api.example.com/mcp
  • Management MCP URL example: https://api.example.com/api/v1/mcp

Local/Desktop MCP config template​

Your repo root already contains an MCP template file: mcp.json.

Use this sanitized pattern for Cursor MCP config (replace placeholders):

{
  "mcpServers": {
    "zerq-gateway-local": {
      "url": "http://localhost:8080/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <GATEWAY_TOKEN_OR_JWT>",
        "X-Client-ID": "<CLIENT_ID>",
        "X-Profile-ID": "<PROFILE_ID>"
      }
    },
    "zerq-gateway-remote": {
      "url": "https://api.example.com/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <GATEWAY_TOKEN_OR_JWT>",
        "X-Client-ID": "<CLIENT_ID>",
        "X-Profile-ID": "<PROFILE_ID>"
      }
    },
    "zerq-management-local": {
      "url": "http://localhost:8080/api/v1/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <OIDC_ACCESS_TOKEN>"
      }
    },
    "zerq-management-remote": {
      "url": "https://api.example.com/api/v1/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <OIDC_ACCESS_TOKEN>"
      }
    }
  }
}

Do not commit real tokens in client config files.

3) Authentication requirements​

Gateway MCP​

Send these headers with requests:

  • Authorization: Bearer <profile-token-or-jwt>
  • X-Client-ID: <client-id>
  • X-Profile-ID: <profile-id>

Management MCP​

Send:

  • Authorization: Bearer <OIDC-token>

Do not send X-Client-ID or X-Profile-ID for management MCP.

4) Session flow (required)​

  1. Send initialize JSON-RPC call.
  2. Store Mcp-Session-Id from response header.
  3. Use same session header for tools/list and tools/call.
  4. Delete session when done.

5) Smoke-test requests​

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

6) Hardening checklist​

  • Use dedicated client/profile for each Cursor integration.
  • Keep profile scope minimal (methods, routes, policy limits).
  • Prefer short-lived credentials and rotate regularly.
  • Track tool activity in request logs and audit logs.