Connect Cursor to SmartGate in 5 Minutes

SmartGate Connect is live in the Dashboard. Here's the fastest path to a working Cursor + MCP setup.

Steps

1. API key — Dashboard → API Keys → Create key
2. Connect — Dashboard → Connect → Cursor tab → Copy JSON
3. Merge into ~/.cursor/mcp.json under mcpServers
4. Restart Cursor
5. Run tools/list — you should see seven smart_* tools

Production URL pattern:

https://smartgate.network/api/mcp

Connect copies the exact value for your deployment.

Common mistakes

• Using Playground config for MCP (they're separate paths)
• Forgetting Authorization: Bearer … in headers
• Using streamable-http instead of legacy SSE

Full details: Connect Guide and MCP Endpoint.

Why Connect is the SSOT

Hosts differ in config paths and JSON shapes. SmartGate standardizes on Streamable HTTP POST {site}/api/mcp with Bearer authentication. Dashboard → Connect always renders the URL for your deployment. Prefer copying from Connect over retyping a blog sample after a domain or path change.

SmartGate does not auto-register into Cursor or other hosts. Keys stay under your control. Each host keeps its own MCP server map. That is deliberate security posture, not missing automation.

Playground vs MCP (read twice)

Playground exercises REST flows for evaluation. It does not load your MCP Connect JSON. "Works in Playground, empty tools in Cursor" almost always means the host never completed initialize / tools/list with the Connect config you thought you pasted.

Verification checklist

1. API key created for the correct team.
2. Cursor tab JSON merged under mcpServers without renaming required headers.
3. Transport is Streamable HTTP (legacy SSE dual-endpoint removed).
4. Cursor restarted or MCP refreshed.
5. tools/list shows seven smart_* tools.
6. One cheap call appears in Activity Logs with the expected team_id.

Failure table

After Connect works

Prefer smart_pipe research templates for audited chains. Add smart_budget_guard before expensive jobs. Turn on compression and dedup when fetch/search overlap. Read Tools, Token Control, and Traffic Customs. Keep English-first docs aligned with the Positioning Bible: intelligence layer, not LLM proxy.

The Cursor config file, field by field

Connect does not hand you an opaque blob; it renders a host-shaped JSON object you merge into a file you already own. For Cursor that file is ~/.cursor/mcp.json for a global server, or .cursor/mcp.json inside a project (lib/connect/mcp-config-templates.ts, PLATFORM_CONFIG_PATH.Cursor). The snippet it builds has this shape:

{
  "mcpServers": {
    "smartgate": {
      "type": "streamable-http",
      "url": "https://smartgate.network/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>",
        "X-SmartGate-Agent-Platform": "cursor"
      }
    }
  }
}

Four things matter. type is streamable-http, because the legacy dual-endpoint SSE flow was removed. url is the single POST /api/mcp path. Under headers, Authorization carries the Bearer key and X-SmartGate-Agent-Platform is set to cursor so Audit Logs label the source correctly. If the file already has an mcpServers map, merge smartgate into it rather than replacing the file. Cursor also resolves ${env:SMARTGATE_API_KEY} inside headers, so you can keep the secret in an environment variable instead of on disk. After editing, restart Cursor or toggle the server under Settings → MCP.

Verifying the handshake with tools/list

A connection is only "working" when the initialize handshake completes and tools/list returns all seven smart_* tools. The server runs the Streamable HTTP transport statelessly (backend/smartgate/api/mcp.py, stateless_http=True, mounted at /mcp), and it ships a compatibility shim (backend/smartgate/api/mcp_session_compat.py) because a surprising share of "empty tools" reports are an initialization race: a client that calls tools/list before initialize finishes gets -32602 (INVALID_PARAMS), which that file's header notes usually means "Received request before initialization was complete", not bad parameters. Restarting the host or refreshing the MCP server clears it.

For a host-agnostic check you can post a JSON-RPC tools/list request directly — the Hermes hint in mcp-config-templates.ts uses exactly this smoke test:

curl -X POST https://smartgate.network/api/mcp \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A populated tool array means the endpoint, key, and transport are all correct. Then run one cheap smart_search or smart_budget_guard call and confirm a matching row appears in Activity Logs.

Why connections fail in the first five minutes

Most first-run failures trace to one of four causes, and none of them is a missing automation step.

• Wrong credential. A 401 means the Authorization header is missing or the key is invalid; the OpenClaw hint in mcp-config-templates.ts puts it plainly — ensure the header contains a valid sk_live_… key. Regenerate and re-paste rather than hand-editing the token.
• Wrong path or transport. SmartGate serves one Streamable HTTP path, POST /api/mcp. Legacy SSE endpoints and GET-based flows are gone, so a stale sample that still points at /messages will fail even though the key is fine.
• Incomplete handshake. The host lists a server but no tools. That is the init race above, not a SmartGate outage — restart the host and re-check tools/list.
• Fair-use throttling. Free and Playground paths use strict fair-use limits and can soft-fail with 429 under burst. That is entitlement behavior, not a broken connection.

SmartGate deliberately does not auto-register itself into Cursor or any other host. Each host keeps its own MCP server map and your keys stay under your control — which is why Connect gives you a copy-paste snippet rather than an install hook.

For the shared operator playbook, production checklist, product links, and closing note, this series keeps exactly one copy — see What Is an MCP Gateway?.

Related

• Connect Guide
• MCP Endpoint
• Agent Builders
• Quick Start

Host notes beyond Cursor

The same Connect workflow applies to Claude Desktop, Windsurf, OpenClaw, Hermes, and generic Streamable HTTP clients: copy the matching tab, merge into the path Connect shows, restart or refresh, then verify tools/list. Official host docs change; SmartGate Connect remains the deployment-specific source for URL and headers. After tools appear, run a cheap smart_budget_guard check or small smart_search before enabling long smart_pipe research templates so the first Activity Log rows stay easy to read.