MCP connection configuration

An MCP connection registers an external MCP (Model Context Protocol) server — for example GitHub, Datadog, or your own server — so Buddy can use its tools during investigation. Connections are owned by the Organization; individual Teams can opt out via disabled_mcp_connections (see Team configuration). For a conceptual overview — how Buddy calls MCP tools, authorization tiers, and custom MCP safety — see MCP integrations.

Spec vs operational state. The Edit-mode JSON (the spec) contains only declarative settings — including connection, your declared intent to use the connection. Credentials, the OAuth connection state, and the Ops-mode suspension are operational state: they are not spec fields. The connection's effective status (shown as a badge in the list, View mode, and Ops mode) is derived from the declared intent, the credential state, and the suspension flag. Snapshots from older versions may still carry a legacy status field, which is ignored — see Version history and rollback.

Spec fields

Investigation hints (free-text Markdown guidance shown to Buddy when this connection's tools are in scope) are edited in a dedicated Markdown editor on the connection page, not in the spec JSON.

Presets and authentication

Each preset comes with a fixed server URL and authentication scheme; you only supply the credential.

Setup flow

1. Create the connection. Open MCPs, pick a preset (or Custom), review the spec in Edit mode, and apply. The template declares "connection": true; since no credential is registered yet, the connection starts in the Awaiting Credential state and a credential dialog opens automatically (closing it without registering shows a reminder — the connection stays inactive until a credential is registered).
2. Register the credential. Paste the token / keys into the dialog (or later via Update credentials in Ops mode). For oauth2 presets, register the Client ID and Client Secret, then switch to View mode and click Connect to complete the OAuth authorization.
3. The connection activates automatically. As soon as the credential is saved (for oauth2, as soon as the OAuth connection completes), the connection becomes Connected. There is no manual enable step.
4. Test the connection. In Ops mode, run the connection test. A successful test also lists the tools the server provides.

Effective status

The list, View mode, and Ops mode show the connection's effective status, derived from the declared intent, the credential state, and the Ops suspension:

Ops mode operations

Ops mode handles day-to-day operations. It can suspend and resume an active connection, but it cannot enable one — enabling happens automatically through the spec's connection declaration plus credential registration:

• Suspend / resume toggle — temporarily suspends an active connection (for example during an incident with the external service) and resumes it later. The toggle is only operable while the connection is active or suspended; for a connection that is Awaiting Credential or Disabled the toggle is inert and a hint explains how to activate it.
• Update credentials — registers the initial credential and rotates it later. Saving a credential on a connection declared with connection: true activates it automatically. Credentials are write-only: they are encrypted at rest and are never shown again or returned by the API.
• Delete credentials — removes the stored credential (token / key connections only; after a confirmation). The connection drops back to Awaiting Credential and stops working until a new credential is registered. For oauth2 presets, use Disconnect in View mode instead.
• Connection test — verifies that Unit Oncall can reach the server with the stored credential, and lists the available tools.
• Tool toggles — enable or disable individual tools in Ops mode (with bulk actions such as disabling all write tools). These are operational state, separate from the disabled_tools spec field: they persist until changed again, but are not version-controlled and are not affected by rollback. To manage a tool declaratively (version-controlled, diffable, rollback-able), add it to disabled_tools in Edit mode.

Custom MCP connections

A custom connection points at your own MCP server instead of a preset. Its spec carries the connection details in addition to the shared fields above:

The transport is fixed to streamable_http. The setup flow is the same as for presets: apply the spec (declaring "connection": true), register the credential, and the connection activates automatically; then test. See Custom MCP safety for the safeguards applied to custom servers.

Version history and rollback

The spec is version-controlled: History mode shows every applied version with a diff, and any version can be rolled back to. Credentials and the Ops suspension are not part of the spec, so rollback never touches them. The connection declaration is part of the spec: rolling back to a version with a different declaration changes whether the connection is in use — in particular, snapshots from before the connection field existed are interpreted as connection: false, so rolling back to one stops the connection. Spec snapshots from older versions may also contain a legacy status field; it is ignored on apply and rollback.

Validation rules

• disabled_tools entries must be strings, must match tool names provided by the server (when the tool list has been fetched), and must not contain duplicates.
• Applying connection: true without a registered credential is accepted — the connection simply stays in Awaiting Credential until the credential is registered (for oauth2 presets, until the OAuth connection completes).
• The Ops suspend / resume toggle only works on a connection that is active or suspended; attempts on a Disabled or Awaiting Credential connection are rejected.
• For custom connections: name must be unique within the Organization; slug must match the format above; server_url must be HTTPS and publicly routable; auth_type must be bearer_token or api_key.

Examples

Minimal spec for a preset connection (defaults):

{
  "connection": true,
  "proactive_investigation": false,
  "disabled_tools": []
}

Opt in to proactive investigation and block two write tools:

{
  "connection": true,
  "proactive_investigation": true,
  "disabled_tools": ["create_issue", "delete_branch"]
}

Spec for a custom connection:

{
  "name": "Internal tools",
  "slug": "internal-tools",
  "description": "Company internal MCP server",
  "server_url": "https://mcp.example.com",
  "auth_type": "bearer_token",
  "connection": true,
  "proactive_investigation": false,
  "disabled_tools": []
}

Related

• MCP integrations — concepts, how Buddy uses MCP tools, tool authorization tiers, and custom MCP safety.
• Team — disabled_mcp_connections hides a connection from a Team; mcp_tool_overrides tightens per-tool authorization.
• Organization settings — ai_enabled master switch for all AI features.