MCP integrations

MCP (Model Context Protocol) lets Buddy call tools that live outside Unit Oncall — for example, search a GitHub repository, query Datadog metrics, or call your own internal service. Each external server is registered as an MCP connection at the Organization level, and the Teams that should use it have it enabled.

Connection types

Type	What it is	Where the URL / auth come from
Preset	Unit Oncall-vetted integrations (for example GitHub, Datadog, New Relic).	Server URL, transport, and auth scheme come from the Unit Oncall preset registry. You only supply the credential through a secret (or sign in via OAuth).
Custom	Your own MCP server.	You supply the server URL, transport, and auth type. See Custom MCP safety.

All MCP connections are owned by the Organization. Per-Team enable/disable is controlled from the Team's disabled_mcp_connections list — see Team configuration.

Configuration reference

These are the fields you can edit on an MCP connection. Field names match the API payload.

Field	Type	Required	Default	Notes
`name`	string	Yes	—	Display name (e.g. "GitHub - unit-oncall").
`description`	string	No	`""`	Free-text description.
`preset_type`	string	Yes for preset	—	Preset key (e.g. `github`, `datadog`). Empty string for custom MCP.
`slug`	string	Yes for custom	—	URL-safe identifier, 2–50 chars, lowercase + digits + hyphen, starts and ends with alphanumeric.
`server_url`	string	Yes for custom	—	HTTPS URL of the MCP server. Validated for SSRF.
`transport`	string	No	`streamable_http`	Transport. Only `streamable_http` is supported.
`auth_type`	string	Yes for custom	—	One of `bearer_token`, `api_key`. (Presets may use `oauth2`, `dd_keys`, `nrak_key`.)
`connection`	boolean	No	`false` on create (the new-connection template sets `true`)	Declarative intent to use this connection. Omitting it on create is treated as `false`; omitting it on update keeps the current value (partial-update compatible). The Edit-mode editor requires the field explicitly. It takes effect automatically once the credential is available (the referenced secret has a value; for OAuth presets, once the OAuth connection completes). Set `false` to stop using the connection.
`credential_secret`	string \| null	No	`null`	Name of the secret that holds the credential: a `static` secret, or for `oauth2` presets a `grant` secret that receives the OAuth tokens. Omitting it on update keeps the current value; `null` removes the reference.
`proactive_investigation`	boolean	No	`false`	Opt-in flag marking this MCP as a proactive investigation target. Proactive investigation performs external API calls and consumes credits, so it is off by default.
`investigation_hints`	string	No	—	Free-text hints (Markdown) shown to Buddy when this MCP's tools come into scope.
`disabled_tools`	array	No	`[]`	Tool names to permanently disable for this connection. A disabled tool is never registered for Buddy, so Buddy cannot accidentally call it.
`icon`	string	No	—	Icon identifier for the UI.

Whether the connection is actually in effect is derived: a connection declared with connection: true activates automatically once its credential is available (the secret named by credential_secret has a value; for OAuth presets, once the OAuth flow completes) — until then it shows as Credential Missing. The Ops view can temporarily suspend and resume an active connection, but cannot enable one; see MCP connection configuration for the full status model.

Authentication

For every auth_type except oauth2, the credential is the value of a static secret: you declare the secret, set its value in the Secret page's Ops mode, and name it in the connection's credential_secret. Rotating the credential means setting a new value for the secret; the connections that reference it pick it up without being edited.

Auth type	Secret value	Sent as
`bearer_token`	A token.	`Authorization: Bearer <token>`
`api_key`	An API key.	`X-API-Key: <key>`
`dd_keys` (Datadog preset)	`<API key>:<Application key>`	`DD-API-KEY` and `DD-APPLICATION-KEY`
`nrak_key` (New Relic preset)	A `NRAK-...` user API key.	`api-key`
`oauth2` (Notion and Atlassian presets)	Written by Unit Oncall into the `grant` secret when you click "Connect" in Ops mode and approve access. Unit Oncall is registered with each service, so you do not create an OAuth app. Unit Oncall refreshes the tokens automatically. See Notion and Atlassian.	`Authorization: Bearer <access token>`

Stored credentials are encrypted before being written to the database and never appear in API responses. Each time Unit Oncall reads a secret's value to connect, the read is recorded in the Organization's audit log.

Use a dedicated account

The credential behind an MCP connection is shared. Buddy uses it for every member of the Organization whose Team has the connection enabled, and for proactive investigations that run without anyone present. We recommend creating a dedicated account at the service for Unit Oncall — a bot user or service account (for OAuth presets, see the note below) — instead of using a person's account:

Access — Buddy can see and change what the account can. Give the dedicated account access only to what investigations need, such as selected repositories, projects, or pages.
Attribution — Actions Buddy takes on the service appear as the dedicated account, not as one of your members.
Continuity — The connection keeps working when the person who set it up changes roles at the service or leaves it. For OAuth presets, the member who clicked Connect must also stay in your Organization: if they leave or are removed, another member must click Connect again.

How to connect with the dedicated account:

Token-based presets and custom connections (for example GitHub, Sentry, Datadog, New Relic) — create the token or key for the dedicated account, either by signing in to the service as that account or, for a service account that cannot sign in, from the service's admin settings. Set it as the secret's value.
OAuth presets (Notion, Atlassian) — when you click Connect in Ops mode, sign in to the service as the dedicated account before you approve access. For these presets the dedicated account must be a regular user account that can sign in through the browser, such as a shared bot user that is a member of your workspace or site. Service accounts that cannot sign in through the browser, such as Atlassian service accounts, cannot be used with Connect.

The dedicated account may need its own seat or license at the service.

How Buddy uses MCP tools

Once a connection is active and enabled for the Team, Buddy can discover and call its tools. The same approval flow applies as for built-in tools (see Buddy AI chat):

Write or destructive tools require an approval card before they run by default. This is the safe default for every MCP tool.
Read tools on vetted preset MCP servers run automatically without approval by default — this lets Buddy gather context (search issues, fetch metrics, look up alerts) without interrupting you. Your Organization's admin can downgrade any specific tool to require approval or hide it entirely via the tool authorization tier controls below (see Tool authorization tiers).
Read tools on custom MCP servers still require approval by default; only an admin can promote them to auto-allow.

Per-Team enable/disable lives on the Team, not the MCP connection: setting disabled_mcp_connections on a Team hides the entire MCP from Buddy for that Team.

Per-tool disable lives on the MCP connection: setting disabled_tools on a connection hides specific tools from Buddy across the Organization.

Tool authorization tiers

Each MCP tool is classified into one of three authorization tiers so Buddy never silently runs a tool that could change or break the outside world. The tier controls whether the tool can run automatically, requires approval, or is hidden from Buddy entirely.

Auto-allow (read) — runs without approval. Default for vetted preset read tools; your Organization's admin can also promote any other tool (including custom MCP tools) to this tier when appropriate.
Requires approval (write / destructive) — Buddy must show the approval card before running. This is the default for everything else and the default for custom MCP tools.
Hidden — Buddy never sees the tool. Used for destructive tools on custom (untrusted) MCP servers.

Self-reported "read-only" hints from custom MCP servers do not automatically lift a tool into auto-allow. Custom servers always default to requires-approval; only an Organization admin can promote a custom tool to auto-allow via an explicit override.

Admins can promote or demote any tool from the MCP connection detail page in Console. Changes are version-controlled and audit-logged, so you can review or roll back tier changes at any time.

Custom MCP safety

A custom MCP connection lets you point at any HTTPS server. Unit Oncall applies the following safeguards on both save and at every connection time:

The server_url scheme must be https.
DNS resolution and the actual TCP connect both reject private IP ranges, loopback, link-local, and other non-routable destinations (SSRF / DNS rebinding protection).
HTTP requests carry a strict timeout.
The credential is kept in a secret, encrypted at rest. It is never returned in any API response.

We still recommend you only point a custom MCP at a server you operate or trust. Treat a custom MCP server the same way you would treat a vendor with API access to your data.

Validation rules

name must be unique within an Organization.
For custom MCP: slug must match ^[a-z0-9][a-z0-9-]{0,48}[a-z0-9]$ (2–50 chars).
For custom MCP: server_url must be HTTPS and must not resolve to a private / loopback / link-local address.
For custom MCP: auth_type must be bearer_token or api_key. (oauth2 is reserved for presets.)
credential_secret must name a secret in the Organization that is not limited to a Team, of kind static (grant for oauth2 presets).
transport must be streamable_http.

Examples

Add the GitHub preset (PAT auth):

On the Secret page, declare a static secret github-pat and, in Ops mode, set its value to a personal access token with the scopes you want (e.g. repo:status, read:org).
Open MCPs → Add → GitHub (preset), set "credential_secret": "github-pat" in the spec, and apply ("connection": true in the template).
The connection activates automatically because the secret already has a value. Buddy can now use the GitHub tools.

Connect Notion via OAuth (preset):

On the Secret page, declare a grant secret notion.
Open MCPs → Add → Notion (preset), set "credential_secret": "notion", and apply.
Sign in to Notion as the dedicated account, then click "Connect" in Ops mode and approve access. Unit Oncall stores the tokens in the notion secret and refreshes them automatically.

On the Secret page, declare a static secret my-tools-token and set its value to the bearer token.
Open MCPs → Add → Custom.
Enter slug = my-tools, server_url = https://mcp.example.com, auth_type = bearer_token, credential_secret = my-tools-token. The server_url must resolve to a publicly routable address — private / loopback / link-local destinations are rejected by SSRF protection.
Save. SSRF validation runs on the URL, and the connection activates automatically.

Disable a single destructive tool on a connection:

Open the connection page → Tools.
Toggle off the tools you do not want Buddy to call (for example delete_repository).
Save. The tool is now permanently disabled across the Organization.

Buddy AI chat — how the approval flow guards write tools, including MCP write tools.
Buddy Knowledge Base — how investigation_hints on an MCP connection enter Buddy's prompt.
Team configuration — disabled_mcp_connections lets a Team hide an Org-wide MCP.
Secret configuration — the secrets that hold MCP credentials.
Organization settings — ai_enabled master switch.