MCP server

Connect any MCP-capable agent (Claude Code, Cursor, Windsurf, Cline, Codex) to Synapse Garden's control plane. Read live catalog, query logs, mint scoped keys.

FIG.

FIG. 00 · MCP SERVERLIVE STATE

@synapse-garden/mcp is a Model Context Protocol server that exposes your Synapse Garden control plane to any MCP-capable agent. It speaks both transports — stdio for local installs and streamable HTTP for hosted clients — and resolves both PATs and OAuth tokens against the same (user, org, scopes) triple your dashboard uses. The agent gets the same view of your account that you do, scoped to whatever you grant.

Install

Three install paths cover every common client. All three point at the same package and the same backend.

claude mcp add synapse-garden -- npx -y @synapse-garden/mcp

Then export your PAT in the shell that runs Claude Code:

export MG_PAT=mg_pat_xxxxxxxxxxxxxxxxxxxxxxxx

# No install. OAuth handshake on first connect.
claude mcp add synapse-garden --transport http https://synapse.garden/api/mcp

The stdio install authenticates with a personal access token in MG_PAT. The hosted install authenticates with OAuth 2.1 + PKCE — the agent opens a browser, you pick the org and scope set on our consent screen, and the access token lives in the agent's secure storage.

Auth

Two paths, one backend. A personal access token (mg_pat_*) is issued from the dashboard at /app/[orgSlug]/agent-tokens. PATs are sha256-hashed at rest, scoped per token, and revocable from the same page. They're the right choice for local stdio installs where the agent runs as you on your machine.

OAuth 2.1 + PKCE is the right choice for hosted clients — Claude Desktop, web agents, anything that can't safely hold a long-lived secret. The agent kicks off the authorization-code flow, you pick the org and scope set on a consent screen we host, and the agent receives a one-hour access token plus a refresh token. The consent screen lists every requested scope in plain English; we re-prompt whenever the scope set widens.

The MCP server never sees mg_live_* proxy keys. Those are minted via the create_api_key tool, and the cleartext is returned to the agent exactly once — the same model the dashboard uses.

FIG. 01HANDSHAKE

SCHEMATIC

The agent presents either a PAT or an OAuth bearer token on every MCP call. The server resolves it to `(user, org, scopes)`, applies the relevant scope check, and dispatches to the right tool, resource, or prompt. RLS still applies — control-plane reads go through the same repo layer the dashboard uses.

Tools

Twelve tools in v1. Read tools answer questions about your account; write tools mutate it and require an explicit confirm: true argument before they take effect.

Tool	R/W	What it does
`list_models`	R	Live catalog — provider, id, modality, pricing, capabilities. Filterable.
`search_models`	R	Natural-language query over the catalog. Returns ranked suggestions.
`recommend_model`	R	Given a task description, returns one to three models with rationale and price comparison.
`list_keys`	R	API keys for the current org and project. Cleartext is never included.
`create_api_key`	W (confirm)	Mint a new `mg_live_` or `mg_test_` key. Returns cleartext exactly once.
`revoke_api_key`	W (confirm)	Revoke a key. Negative-cached for 60s on the proxy.
`set_project_budget`	W (confirm)	Set a daily or monthly USD ceiling. Returns the new budget snapshot.
`set_model_allowlist`	W (confirm)	Replace a project's model allowlist. Returns the diff.
`query_logs`	R	Time-bounded query over `request_logs` and `usage_aggregates`. Capped at 1000 rows.
`analyze_spend`	R	Top spenders by project, model, and day, with anomaly flags.
`tail_errors`	R	Last N 4xx and 5xx responses with redacted payloads.
`migration_plan`	R	Given a code snippet, returns the diff to migrate to Synapse Garden plus the env vars to set.

Resources

Five named resources. The agent fetches them via read_resource so it doesn't have to parse free-form JSON every call.

URI	Content
`mg://catalog`	The full live `/v1/models` response, JSON, refreshed hourly.
`mg://org/current`	Current org id, slug, plan tier, and the caller's role.
`mg://project/{id}/snapshot`	Project budget, allowlist, and recent throughput.
`mg://errors/recent`	Last 50 errors across every project in scope.
`mg://docs/index`	Sitemap of `content/docs/**` so the agent can `read_resource` a specific guide instead of guessing URLs.

Prompts

Three named prompts compose tools into common flows. Vanilla MCP clients without skill support can still reach the recipe surface this way.

Prompt	Purpose
`audit-spend`	"Why did my bill spike?" — runs `analyze_spend`, formats the answer, suggests a budget.
`migrate-from`	"Migrate my OpenAI calls to Synapse Garden" — runs `migration_plan`, applies the diff, mints a key.
`harden-project`	"Make project X enterprise-ready" — sets allowlist, budget, rotates the key, enables alerts.

Confirmation flow

Mutations always confirm

Every write tool requires confirm: true. On the first call without it, the server returns a structured "confirmation required" response with a human-readable summary of what would change. The agent surfaces that summary, you approve or reject, and the agent re-issues with confirm: true. Silent spend is impossible by design.

Error envelope

Every tool returns errors in a stable shape so the agent can branch on code without parsing the human message:

{
  "error": {
    "code": "SCOPE_MISSING",
    "message": "This tool requires the keys:write scope. Re-issue your token with that scope from /app/[orgSlug]/agent-tokens.",
    "details": {
      "required": ["keys:write"],
      "granted": ["keys:read", "models:read", "logs:read"]
    }
  }
}

Common codes the agent should know: SCOPE_MISSING, CONFIRM_REQUIRED, RATE_LIMITED (per-token rate limit, 60 RPM), NOT_FOUND, INVALID_ARGUMENT, UPSTREAM_ERROR.

Status

All 12 tools live · stdio + hosted HTTP

All read tools (list_models, search_models, recommend_model, list_keys, query_logs, analyze_spend, tail_errors) and all confirm-gated write tools (create_api_key, revoke_api_key, set_project_budget, set_model_allowlist, migration_plan) ship today, plus all five resources and three prompts. The hosted streamable-HTTP transport is live at https://synapse.garden/api/mcp with OAuth 2.1 + PKCE.

MCP server

On this page