How to set up the incident.io MCP server

incident.io manages the incident lifecycle, alerts, escalations, on-call schedules, and operational follow-up. Its hosted MCP server can authenticate interactively as an incident.io user through OAuth or non-interactively with a scoped API key.

This guide covers the incident.io-side setup for any compatible MCP client. The incident.io agent template separately deploys a governed agent in Dome.

Before you start

• Confirm that your incident.io organization is on Team, Pro, or Enterprise; the remote MCP server is not available on Basic. Before any OAuth attempt, an administrator must enable it in Settings → MCP.
• Search Settings for MCP. If there is no MCP setting, stop before starting OAuth: remote MCP is not provisioned for that organization. Ask the organization owner or incident.io support to confirm plan eligibility and enable the feature.
• Choose a dedicated test user and a known test incident, alert, schedule, or catalog entry. Do not use an organization owner for routine testing.
• If you are using an MCP client whose redirect host is not built in to incident.io, an administrator must add that host under Settings → MCP server → Allowed redirect domains. For Dome, add api.domesystems.ai.

Recommended: OAuth

Use OAuth when the MCP connection should act as a person. The connection inherits that user's visibility and permissions, while incident.io's authorization screen lets you select a Read only access level.

1. In incident.io, open Settings → MCP and enable the remote MCP server. This organization-level switch must be on before anyone can authorize an MCP client. If the page is missing, have the organization owner or incident.io support enable remote MCP before continuing.
2. Add api.domesystems.ai to Allowed redirect domains if you are connecting from Dome. Enter only the host; do not enter a callback URL or path.
3. Create or choose a dedicated test user with access only to the teams, incidents, alerts, schedules, and catalog data that the agent should inspect.
4. Start the MCP client's OAuth flow and sign in as that test user. Select the intended incident.io organization, then choose Read only on the access screen.
5. Use the MCP identity_show tool to confirm that access_level is read_only. Read a known test resource and verify a private incident or a resource owned by an unapproved team is unavailable.

incident.io uses standard MCP OAuth with automatic client registration and PKCE. Dome handles that registration, so do not create an OAuth client or client secret. See incident.io's remote MCP server documentation for its current endpoint, authorization behavior, and redirect-domain rules.

Alternative: Dedicated API key

Use a dedicated API key only for a non-interactive integration. API keys do not show an OAuth read-only selector, so restrict the key itself to the smallest required read permissions and teams.

1. In incident.io, open Settings → API keys and create a new key for this MCP integration.
2. Give the key a clear integration-specific name and grant only the permissions it needs. For a read-only incident and on-call setup, start with View data, View catalog, View on-call resources, and Read schedules, adding View all incident data only when private incidents are explicitly required.
3. Where a permission supports it, scope the key to only the approved teams. Do not add incident editing, workflow, escalation, schedule-editing, or status-page permissions to a read-only integration.
4. Copy and store the secret immediately: incident.io displays the full token only at creation. Keep it in the MCP client's secret store, record its owner and rotation date, and revoke it when testing ends.
5. Configure the MCP client to send the key as a bearer token, then test a permitted resource and a denied boundary.

See incident.io's API key documentation for its permission model, team-scoped access, and rotation guidance.

Verify incident.io MCP

• Confirm that incident.io MCP tools are discovered after authentication.
• Use identity_show to confirm the expected organization and, for OAuth, read_only access.
• Read one known test incident, alert, on-call schedule, or catalog entry.
• Attempt to read a private incident or a resource owned by an unapproved team; it should be unavailable or denied.
• Attempt a change only in a controlled test: a read-only OAuth connection should reject it, and an API key should lack the corresponding write permission.

Troubleshooting

• No MCP setting, or “The MCP server isn't available for [organization]”: remote MCP is disabled or not provisioned for that organization. An admin should first search Settings for MCP; if it is absent, ask the organization owner or incident.io support to confirm plan eligibility and enable the feature. If it is present, enable it and restart the OAuth flow.
• Authorization fails before consent: confirm that remote MCP is enabled and that the client redirect host is listed under Settings → MCP server → Allowed redirect domains. For Dome, the allowed host is api.domesystems.ai.
• OAuth connects but has too much or too little access: reconnect with the intended user and select the correct organization and Read only access level. The connection can only see what that user can see.
• API key can access the wrong resources: remove broad account-level permissions and use team-scoped permissions wherever available. A key can only receive permissions that its creator already has.
• Changes are unexpectedly rejected: that is expected for an OAuth connection approved as read-only or an API key without the needed write permission. Preserve the restricted credential rather than broadening it for a test.

Next steps

Deploy the incident.io agent template to create a governed agent in Dome that can investigate the approved incident and on-call context with its included model, tools, and rules.