Configuring the Synapse MCP

The Synapse MCP server exposes Corti's Mimir (metrics) and Loki (logs) to AI coding harnesses via the Model Context Protocol. This page covers the simplest setup — OpenCode's native remote transport, authenticated via Keycloak SSO — the same way the Linear MCP works. No extra binaries or sidecar files. We'll add setup snippets for other harnesses (Cursor, Codex, Crush) as we go.

Server-side context. The MCP server itself (mcp-grafana behind Envoy Gateway with Keycloak JWT validation) is deployed by the synapse-mcp Helm chart. The chart serves MCP-spec OAuth discovery (/.well-known/oauth-protected-resource) so standard MCP clients can auto-discover Keycloak and run the PKCE browser flow with the pre-registered synapse-mcp client — no realm-wide Dynamic Client Registration.

The config block

Add this to your OpenCode config. The global config is ~/.config/opencode/opencode.json (NOT ~/.opencode/); a project config is ./opencode.json at the repo root.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "synapse": {
      "type": "remote",
      "url": "https://mcp.synapse.corti.app/mcp",
      "enabled": true,
      "oauth": {
        "clientId": "synapse-mcp",
        "scope": "openid email profile offline_access"
      }
    }
  }
}

That's the whole thing. It sits alongside any other MCP servers you already have (e.g. linear).

Why each field

field	value	why
`type`	`"remote"`	OpenCode connects over HTTPS to the remote server. No local process to run.
`url`	`https://mcp.synapse.corti.app/mcp`	The Envoy Gateway route to the `mcp-grafana` pod on prd-par01.
`oauth.clientId`	`"synapse-mcp"`	The pre-registered Keycloak public client. Supplying it makes OpenCode skip Dynamic Client Registration and use this client directly (PKCE S256, no secret).
`oauth.scope`	`"openid email profile offline_access"`	`offline_access` gives OpenCode a refresh token, so the connection survives long idle periods (verified: works after 12h off) without a browser re-auth.
`enabled`	`true`	Loads the server on startup.

No clientSecret — the synapse-mcp Keycloak client is a public PKCE client (public_client: true, create_secret: false).

Authenticating

After saving the config, quit and restart OpenCode (config loads once at startup). Then trigger the OAuth flow:

opencode mcp auth synapse

This opens your browser for Corti SSO (the same identity you use for console.corti.app / auth.eu.corti.app). After you authorize, OpenCode stores the tokens securely in ~/.local/share/opencode/mcp-auth.json.

Verify it worked:

opencode mcp list          # lists all MCP servers + their auth status

You should see synapse showing as authenticated. The simplest end-to-end check is to just use the tools — ask the agent to run a Mimir or Loki query.

To clear stored credentials and re-auth from scratch:

opencode mcp logout synapse

How authentication works end-to-end

OpenCode → POST /mcp (no token) → Envoy Gateway → 401 + WWW-Authenticate
OpenCode → fetch /.well-known/oauth-protected-resource → discovers Keycloak
OpenCode → Keycloak OAuth 2.1 authorize (PKCE, client=synapse-mcp) → browser SSO
OpenCode → POST /mcp, Authorization: Bearer <Keycloak JWT>
Envoy Gateway → validates JWT vs realm JWKS → rewrites Authorization to internal marker
Envoy → mcp-grafana pod → Grafana datasource proxy (read-only SA) → Mimir/Loki

The Keycloak JWT is short-lived (~5 min) and refreshed silently by OpenCode via the offline_access refresh token. Per-user identity (sub/email) is visible in Envoy access logs for audit; Grafana-side attribution is a shared read-only service account.

What you get

Once connected, the synapse_* tool families are available to the agent:

Mimir — synapse_query_prometheus, synapse_query_prometheus_histogram, synapse_list_prometheus_* (metrics, labels, metadata)
Loki — synapse_query_loki_logs, synapse_query_loki_stats, synapse_query_loki_patterns, synapse_list_loki_label_* (logs, labels)
Grafana — synapse_search_dashboards, synapse_get_dashboard_*, synapse_check_datasources_health, alerting tools, deeplinks

Datasource UIDs: mimir (Prometheus) and loki (Loki).