Docs/MCP Proxy

MCP Proxy

How SatGate proxies MCP tool calls — session management, upstream routing, and tool discovery.

What is the MCP Proxy?

The MCP Proxy is SatGate's core component for AI agent governance. It speaks the Model Context Protocol (MCP) — the same protocol that Cursor, Claude Code, and other AI tools use to discover and call tools.

Your agent connects to SatGate instead of directly to your tool servers. SatGate authenticates the agent, discovers tools from upstream servers, and proxies every tool call — adding cost tracking, budget enforcement, and audit logging along the way.

Request flow

Agent (Cursor)
  │
  ├─ SSE Connect ──→ SatGate MCP Proxy
  │                    │
  │                    ├─ Validate macaroon token
  │                    ├─ Extract tenant_id caveat
  │                    ├─ Load tenant upstreams (cached 60s)
  │                    ├─ Connect to upstreams (parallel)
  │                    └─ Discover tools from all upstreams
  │
  ├─ tools/list ───→ Return merged tool list
  │                   (all upstreams + built-in ping)
  │
  ├─ tools/call ───→ Route to correct upstream
  │                    │
  │                    ├─ Check budget (if enforcement enabled)
  │                    ├─ Forward call to upstream
  │                    ├─ Deduct credits from budget
  │                    ├─ Publish event to event pipeline
  │                    └─ Return result to agent
  │
  └─ keepalive ────→ Refresh session TTL (every 15s)

Session management

Each agent connection creates an SSE session. Sessions are tracked and refreshed by keepalive events. The MCP Monitor on the dashboard shows active sessions in real-time.

Session lifecycle events (session_connect, session_close, session_keepalive) are published to the event pipeline for the dashboard to consume.

Multi-upstream routing

Tenants can have multiple upstream MCP servers. The proxy connects to all of them in parallel for fast tool discovery. Upstream configs are hot-reloaded — add or remove upstreams without restarting.

When an agent calls a tool, the proxy routes the call to whichever upstream advertised that tool. If an upstream goes down, the proxy auto-reconnects with exponential backoff.

Built-in tools

Every SatGate proxy includes a ping tool — a zero-cost health check that agents can call to verify their connection is working. It requires no upstream and always returns immediately.

Event pipeline

Every significant event is published to the event pipeline:

  • tool_call — agent called a tool (name, cost, duration)
  • budget_spend — credits deducted from budget
  • budget_exhausted — budget hit zero
  • auth_failure — invalid or expired token
  • session_connect / session_close — session lifecycle

The enterprise gateway subscribes to these events and pushes them to dashboard clients via WebSocket.

Related