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 credentials (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 a credential is registered (for OAuth presets, once the OAuth connection completes). Set `false` to stop using the connection.
`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 registered (for OAuth presets, once the OAuth flow completes) — until then it shows as Awaiting Credential. 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

How credentials are stored depends on the connection's auth_type:

Auth type	How it works
`bearer_token`	You paste a token. The token is encrypted at rest and sent as `Authorization: Bearer <token>`.
`api_key`	You paste an API key. The key is encrypted at rest and sent as `X-API-Key: <key>`.
`dd_keys` (Datadog preset)	You paste `api_key:app_key`. Both are encrypted at rest. Sent as `DD-API-KEY` and `DD-APPLICATION-KEY`.
`nrak_key` (New Relic preset)	You paste a `NRAK-...` user API key. Sent as `api-key`.
`oauth2` (selected presets)	You click "Connect" and complete the OAuth flow. Unit Oncall stores access and refresh tokens encrypted at rest, and refreshes them automatically.

All stored credentials are encrypted before being written to the database; they never appear in API responses.

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 you provide is 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.)
transport must be streamable_http.

Examples

Add the GitHub preset (PAT auth):

Open MCPs → Add → GitHub (preset) and apply the spec ("connection": true in the template).
Paste a personal access token with the scopes you want (e.g. repo:status, read:org) into the credential dialog.
The connection activates automatically once the token is saved. Buddy can now use the GitHub tools.

Connect Datadog via OAuth (preset):

Open MCPs → Add → Datadog (preset).
Click "Connect" and complete the Datadog OAuth flow.
Save. Unit Oncall stores the access and refresh tokens encrypted; tokens refresh automatically.

Open MCPs → Add → Custom.
Enter slug = my-tools, server_url = https://mcp.example.com, auth_type = bearer_token. The server_url must resolve to a publicly routable address — private / loopback / link-local destinations are rejected by SSRF protection.
Paste the bearer token.
Save. SSRF validation runs on the URL. The token is encrypted at rest, 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.
Organization settings — ai_enabled master switch.