Gamut

Integrations

Remote MCP Servers

Remote MCP servers give agents tools from any external service that implements the Model Context Protocol. Gamut acts as the MCP client and proxies every call.

How MCP works

The Model Context Protocol (MCP) is an open standard for discovering and invoking tools over HTTP using JSON-RPC:

  1. Initialize: The client sends an initialize request with its capabilities. The server responds with its own.
  2. Discover tools: The client sends tools/list. The server returns each tool's name, description, and typed input schema.
  3. Call tools: The client sends tools/call with a tool name and arguments. The server executes the tool and returns the result.

Servers respond with standard JSON or Server-Sent Events (SSE) for streaming.

Registering a server

No authentication

  1. Open Settings > Connections and click Add Connection.
  2. Select MCP Server as the integration type.
  3. Enter a display name and the server's URL.

Gamut connects, performs the MCP handshake, and discovers the available tools. If the connection succeeds, the server is saved with its tool list.

Bearer token

For servers that require a static bearer token, select Bearer Token as the authentication type and enter the token. Gamut sends it in the Authorization: Bearer <token> header on every request. If the server rejects the token (401), Gamut reports the error and does not save the server.

OAuth

Add the server by URL as above. When Gamut receives a 401 and detects an OAuth-capable server (via the WWW-Authenticate header and RFC 9728 resource metadata), it prompts to connect via OAuth. Selecting OAuth as the authentication type starts the flow directly.

Gamut then runs the full discovery flow: it probes the server for a 401 response with a WWW-Authenticate header, fetches Protected Resource Metadata (RFC 9728) to locate the authorization server, and fetches Authorization Server Metadata (RFC 8414 / OpenID Connect Discovery) for the authorization and token endpoints. If the server supports dynamic client registration (RFC 7591), Gamut registers itself automatically.

A popup opens with the authorization server's consent screen. After you authenticate and grant permissions, Gamut exchanges the authorization code for tokens using PKCE (S256), saves the server, and discovers tools.

Custom client credentials

For OAuth servers without dynamic client registration, provide your own credentials:

  • Client Name: display name used during dynamic registration (defaults to "Gamut").
  • Client ID: a pre-registered OAuth client ID.
  • Client Secret: the matching client secret, if applicable.

Tool discovery

Discovery sends three requests: initialize (protocol version 2025-03-26), a notifications/initialized notification, then tools/list. Discovered tools are cached in the database, each with:

  • name: the tool's identifier, such as search_contacts or create_issue.
  • description: what the tool does, in plain language.
  • inputSchema: a JSON Schema for the tool's input parameters.

Re-run discovery at any time with Discover Tools on the server's detail page, for example after the server adds new tools.

Server status

  • Active: The server is connected and operational. Mapped agents can invoke its tools.
  • Error: The last connection attempt failed. The error message is stored and displayed. Common causes are network issues, server downtime, or server-side errors.
  • Auth Required: The OAuth token expired and could not be refreshed, or the server returned a 401 during a proxied request. Click Reconnect on the server row to start a new OAuth flow.

Token refresh

For OAuth-authenticated servers, the MCP proxy refreshes tokens automatically. Before forwarding a request it checks tokenExpiresAt; if the token has expired and a refresh token exists, it calls the OAuth token endpoint, stores the new access token (and any new refresh token), and the request proceeds. On failure, the server's status becomes auth_required and the agent receives a 401.

The refresh request includes the resource parameter from the original discovery, so the new token stays scoped to the correct MCP server.

The MCP proxy

Agent calls to a registered server route through the MCP proxy, which follows the same security model as the connected accounts proxy: synthetic token validation, a mapping check, token injection, streaming passthrough (including SSE), and audit logging. The MCP-specific step is policy enforcement: for tools/call requests, the proxy parses the JSON-RPC body, extracts the tool name, and resolves that tool's policy. Protocol-level methods like initialize and tools/list bypass policy checks. See MCP Tool Policies.

URL validation

Server URLs must be HTTP or HTTPS. Private and loopback addresses (10.x.x.x, 192.168.x.x) are blocked, except localhost in the Electron desktop app, where local MCP servers are common.

Ownership in auth mode

In auth mode, each MCP server belongs to the user who registered it. Users see and manage only their own servers; admins see and manage all of them.

Related