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, and credential_secret, the name of the secret that holds the credential. The credential value itself, 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, whether the credential is available, 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

Field	Type	Required	Default	Notes
`connection`	boolean	Yes	—	Declarative intent to use this connection. The new-connection template sets `true` (creating a connection implies you intend to use it). The connection becomes active automatically once its credential is available (the referenced secret has a value; for `oauth2` presets, once Connect has stored the OAuth tokens in the secret) — there is no separate enable step. Set `false` to stop using the connection. Applying a spec that omits the key (specs from before this field existed) is interpreted as `false`.
`credential_secret`	string \| null	No	`null`	Name of the secret that holds this connection's credential. The secret must exist in the Organization and must not be limited to a Team. Its kind must be `static` — or `grant` for `oauth2` presets, whose tokens are written into the secret when you Connect in Ops mode. A `grant` secret that already holds tokens from a different service cannot be used. `null` = no credential. A `static` secret's value is entered on the Secret page — see Presets and authentication for the value each preset expects.
`proactive_investigation`	boolean	Yes	—	When `true`, Buddy proactively uses this connection while investigating an incident, without waiting to be asked. The new-connection template sets `false` (opt-in): proactive calls reach the external service and consume credits.
`disabled_tools`	array	No	`[]`	Tool names to permanently disable for this connection. A disabled tool is never registered for Buddy. Each entry must match a tool name provided by the server (tool names are listed in View mode); duplicates are rejected.

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. For every scheme except oauth2, the credential is the value of the static secret named by credential_secret, set in the Secret page's Ops mode. Leading and trailing whitespace in the value, such as a trailing newline left by pasting, is removed before the value is sent to the MCP server. For oauth2, credential_secret names a grant secret that receives the OAuth tokens when you connect.

Preset	Auth type	Credential you provide
GitHub	`bearer_token`	A personal access token (PAT) as the secret's value.
Sentry	`bearer_token`	An auth token as the secret's value.
Slack	`bearer_token`	A token as the secret's value.
Datadog	`dd_keys`	The API key and the Application key joined by a colon as the secret's value: `<API key>:<Application key>`.
New Relic	`nrak_key`	A `NRAK-...` user API key as the secret's value.
Atlassian (Jira/Confluence)	`oauth2`	A `grant` secret in `credential_secret`; then Connect in Ops mode. An admin of your Atlassian organization must allow Unit Oncall's domain first — see Notion and Atlassian.
Notion	`oauth2`	A `grant` secret in `credential_secret`; then Connect in Ops mode. See Notion and Atlassian.

Setup flow

Before you start, prepare a dedicated account at the service to create the credential with — a bot user or service account, or for oauth2 presets a regular user account that can sign in through the browser. Every member who uses Buddy shares the connection's credential, so we recommend not using a person's account. See Use a dedicated account.

Declare the secrets. On the Secret page, declare secrets that are not limited to a Team and set the values of the static ones in Ops mode. See Secret configuration.
- Most presets: one static secret for the token or key (for example github-pat).
- oauth2 presets (Notion, Atlassian): a grant secret for the tokens (for example notion). It has no value to enter; Connect writes the tokens into it.
Create the connection. Open MCPs, pick a preset (or Custom), fill in credential_secret in Edit mode, and apply. The template declares "connection": true. Applying only saves the spec — no dialog or setup prompt follows. Creating a custom connection takes you to the new connection's page. Until the credential is available, the connection is in the Credential Missing state and View mode shows why.
Connect (oauth2 presets only). Click Connect in Ops mode, sign in to the service as the dedicated account, and approve access on the service's page. Unit Oncall stores the tokens in the grant secret and refreshes them automatically. Check the preparation in Notion and Atlassian first. Unit Oncall records you as the member who connected: if you leave the Organization or are removed, the connection stops until another member clicks Connect again, and while your account is locked or suspended, the connection is not used.
The connection activates automatically. As soon as the credential is available — the static secret has a value, or the grant secret holds tokens — the connection becomes Connected. There is no manual enable step.
Test the connection. In Ops mode, run the connection test. A successful test also lists the tools the server provides.

To rotate a credential, set a new value for the secret in the Secret page's Ops mode. Every connection that references the secret uses the new value; the connections themselves do not change.

Notion and Atlassian

The Notion and Atlassian presets connect to each service's own MCP server — Notion's at https://mcp.notion.com/mcp, and the Atlassian Rovo MCP server at https://mcp.atlassian.com/v2/mcp — through OAuth. You do not create an OAuth app: Unit Oncall is registered with each service. All you provide is a grant secret in credential_secret and the approval when you Connect.

Before you click Connect, sign in to the service in your browser as the dedicated account you want the connection to use. The connection acts with that account's access.

Atlassian. Atlassian lets the Rovo MCP server redirect only to domains your organization allows. An admin of your Atlassian organization must add Unit Oncall's domain, api.unit-oncall.com, to the allowed domains for the Rovo MCP server. Until then, Atlassian's consent page shows "Access to this domain is restricted" and the connection stops there. See Atlassian's guide, Understand Atlassian Rovo MCP server, for how admins manage the allowed domains. On the consent page you choose the site and the permissions (read, write, search) to grant; the connection can only do what those permissions allow.

Notion. Notion may mark Unit Oncall as unverified in your workspace's list of connections. You can still connect and use it.

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:

Status	Meaning
Connected	`connection: true`, credential available, not suspended — Buddy can use the connection's tools.
Credential Missing	`connection: true` but the credential is not available: `credential_secret` is not set, the `static` secret has no value, or (for `oauth2`) the `grant` secret is not connected or holds tokens this connection cannot use (for example tokens from another service). Set the secret's value — or Connect — to activate.
Suspended	Temporarily suspended in Ops mode. Turn the toggle back on to resume.
Disabled	`connection: false` — declared as not in use. Set `connection: true` in Edit mode to use it.
Error	The connection is active but a health check detected an error, or (for `oauth2`) the connection stopped working after it was connected: the service rejected the stored tokens, the connection expired, connecting failed, or the member who clicked Connect is not available in your Organization (they left or were removed, or their account is locked or suspended). Connect again to fix it — any member who can manage the connection can do this.

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 an available credential:

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 Credential Missing or Disabled the toggle is inert and a hint explains how to activate it.
Connect / Disconnect (oauth2 presets only) — Connect sends you to the service to approve access and stores the tokens in the grant secret named by credential_secret. Disconnect deletes the stored tokens (the secret itself stays). Ops mode also shows the connection state (connected, expired, or failed, with the expiry time) and the member who connected. For the other schemes the credential lives in the static secret named by credential_secret: set, roll back, or delete its value in the Secret page's Ops mode. Deleting a secret's value — or disconnecting a grant secret — moves every connection that references it to Credential Missing.
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:

Field	Type	Required	Default	Notes
`name`	string	Yes	—	Display name. Must be unique within the Organization.
`slug`	string	Yes (create only)	—	URL-safe identifier, 2–50 chars, lowercase letters / digits / hyphens, starting and ending with an alphanumeric. Cannot be changed after creation, so it appears only in the create document and is absent from the spec afterwards.
`description`	string	No	`""`	Free-text description.
`server_url`	string	Yes	—	HTTPS URL of the MCP server. Must resolve to a publicly routable address — private, loopback, and link-local destinations are rejected.
`auth_type`	string	Yes	—	One of `bearer_token` or `api_key`. (`oauth2` and the key-pair schemes are reserved for presets.)

Creation and editing take different documents. The create document is the table above plus connection and credential_secret; proactive_investigation and disabled_tools are not accepted there and are configured after the connection exists (see Examples).

The transport is fixed to streamable_http. The setup flow is the same as for presets: declare a static secret and set its value, apply the spec (declaring "connection": true and credential_secret), 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. credential_secret is part of the spec, so rolling back restores the secret the version referenced (the rollback is rejected if the secret no longer qualifies — see Validation rules). Secret values, stored OAuth tokens, 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 the legacy fields status, oauth_client_id, and oauth_client_secret; they are 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.
credential_secret must name a secret that exists in the Organization, is not limited to a Team, and is of kind static (grant for oauth2 presets). A grant secret that holds tokens from a different service is rejected. If Ops mode reports that the stored tokens can no longer be used, Connect again to replace them.
The same checks apply when rolling back to an earlier version.
Applying connection: true while the credential is not available is accepted — the connection simply stays in Credential Missing until the secret has a value (for oauth2 presets, until you connect).
Connect requires credential_secret (a grant secret).
A secret referenced by a connection (through credential_secret) cannot be removed from the Secret configuration, change its kind, or be limited to a Team. Point the connection at another secret (or set the field to null) first.
The Ops suspend / resume toggle only works on a connection that is active or suspended; attempts on a Disabled or Credential Missing 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 that uses the secret github-pat:

{
  "connection": true,
  "credential_secret": "github-pat",
  "proactive_investigation": false,
  "disabled_tools": []
}

Opt in to proactive investigation and block two write tools:

{
  "connection": true,
  "credential_secret": "github-pat",
  "proactive_investigation": true,
  "disabled_tools": ["create_issue", "delete_branch"]
}

An oauth2 preset (Notion, Atlassian): the tokens go into the grant secret notion when you Connect:

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

Creating a custom connection — the document you fill in on the new-connection page. It carries slug, and it does not take proactive_investigation or disabled_tools; those are set afterwards, on the connection's own page:

{
  "name": "Internal tools",
  "slug": "internal-tools",
  "description": "Company internal MCP server",
  "server_url": "https://mcp.example.com",
  "auth_type": "bearer_token",
  "connection": true,
  "credential_secret": "internal-mcp-token"
}

Spec of that connection once it exists — this is what Edit mode shows and what History mode versions. slug is gone (it cannot be changed after creation) and the two shared fields are now part of the spec:

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

MCP integrations — concepts, how Buddy uses MCP tools, tool authorization tiers, and custom MCP safety.
Secret configuration — declaring the secret that credential_secret names, and setting its value.
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.