MCP Endpoint

Docs

MCP Endpoint

Connect Cursor and other MCP clients to SmartGate via Streamable HTTP and API keys.

SmartGate exposes a Model Context Protocol (MCP) server over Streamable HTTP (MCP 2025-03-26). Use it from Cursor, Claude Desktop, Windsurf, Hermes, OpenClaw, or any client that supports remote MCP with Bearer authentication.

Legacy HTTP+SSE dual-endpoint transport (MCP 2024-11-05) has been removed. All clients must use POST JSON-RPC to a single URL.

Authentication

Every request must include your team API key:

Authorization: Bearer sk_live_...

Create keys under Dashboard → API Keys. Do not commit keys to git or share them in public repos.

Optional header for audit logs:

X-SmartGate-Agent-Platform: cursor

Endpoint

Environment	MCP URL	Method
Production (via app)	`{NEXT_PUBLIC_APP_URL}/api/mcp`	POST
Local dev (via BFF)	`http://localhost:3000/api/mcp`	POST
Local dev (direct Python)	`http://localhost:8000/mcp/`	POST

Example tools/list:

curl -X POST https://smartgate.network/api/mcp \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "X-SmartGate-Agent-Platform: cursor" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

JSON-RPC `method`	Purpose
`initialize`	Session handshake
`tools/list`	Discover tools
`tools/call`	Invoke a tool — `params.name` = tool id, `params.arguments` = args

OpenClaw quirk: Some builds send "method": "smart_fetch" (tool name as method) instead of "method": "tools/call". SmartGate normalizes these requests automatically on the server.

Per-host setup

Host	Config file	Transport	Docs
Cursor	`~/.cursor/mcp.json`	`streamable-http` (recommended)	cursor.com/docs/mcp
Claude Desktop	`claude_desktop_config.json`	`type: streamable-http`	Claude Code MCP
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`serverUrl` + `streamable-http`	Windsurf MCP
OpenClaw	`~/.openclaw/openclaw.json` → `mcp.servers`	`transport: streamable-http`	OpenClaw MCP
Hermes	`~/.hermes/mcp.json`	`streamable-http` POST only	Hermes MCP
Generic	Host-specific	`streamable-http`	MCP Transports

OpenClaw CLI example:

openclaw mcp set smartgate '{"url":"https://smartgate.network/api/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${SMARTGATE_API_KEY}"}}'

Use Dashboard → Connect for copy-paste JSON per platform.

Audit headers (REST)

Optional headers on POST /api/v1/* REST calls. Values appear in activity logs and power Dashboard → Logs → Tasks aggregation.

X-SmartGate-Correlation-Id: <task-uuid>
X-SmartGate-Agent-Platform: openclaw
X-SmartGate-Route: rest
X-SmartGate-Trace-Id: <session-uuid>

MCP Streamable HTTP calls without headers get route=mcp automatically.

Supported MCP hosts

Any client that supports remote Streamable HTTP and custom Bearer headers, including Cursor, Claude Desktop, Windsurf, Hermes, OpenClaw, Cline, Zed, and custom agents.

For AI hosts (protocol)

On initialize, the server returns Server Instructions. On tools/list, each tool includes an English description, inputSchema, and annotations.

Tools (7)

MCP tool	Purpose
`smart_fetch`	Fetch URL → Markdown
`smart_search`	Multi-engine search
`smart_context_gate`	Prompt compression
`smart_dedup`	Semantic deduplication
`smart_budget_guard`	Budget check / count / record
`smart_memory`	Memory add / search / get / delete
`smart_pipe`	Pipeline templates or custom steps

`smart_pipe` step names

In custom steps, use module names (fetch, search, context_gate, dedup, budget_guard, memory) or the same smart_* names as MCP tools. Built-in templates: research, read, remember.

Client compatibility appendix

Some clients send "params": [] or "arguments": []; SmartGate normalizes those to {} before validation.
Do not pass a foreign team_id to smart_budget_guard unless you intend to target that tenant.

Legacy transport removed

The following paths return 405 or 410 with migration JSON:

GET /api/mcp → 405 (use POST)
/api/mcp/messages → 410 (removed)
Python /mcp-sse/* → 404 (unmounted)

See Dashboard → Connect for current configuration templates.

Connect Guide Security