---
title: "Connect AI agents (MCP)"
description: "Let AI agents investigate your incidents, alerts and catalog through Firefight's MCP server, and act through the tools you allow."
canonical: https://firefight.app/docs/api/mcp-server/
---

# Connect AI agents (MCP)

Firefight ships a [Model Context Protocol](https://modelcontextprotocol.io) server, so AI agents like Claude can investigate your incidents directly. An agent connected over MCP can search incidents, pull a full incident timeline, inspect alerts and how they routed, look up ownership in the service catalog, and dry-run your alert routing rules. It can also maintain your catalog, runbooks and routing rules, and resolve approvals, when the credential it uses has permission to. Everything an agent does is recorded under **Developer → Activity**.

## Endpoint

The server speaks Streamable HTTP at a single endpoint.

```
POST https://app.firefight.app/mcp
```

Every request is self-contained, and all data is scoped to the workspace of the token you authenticate with.

## Authenticating

There are two ways to connect, depending on what your MCP client supports.

### OAuth, for interactive clients

Clients that support MCP OAuth, such as Claude Code, connect without you ever handling a token. Add the server and start using it.

```sh
claude mcp add --transport http firefight https://app.firefight.app/mcp
```

On first use, your browser opens Firefight's consent screen, which names the client asking for access, your workspace, and you. Click Authorize and the client is connected. The client registers itself automatically through dynamic client registration, PKCE is required, and access tokens are short-lived with refresh rotation. The connection acts as you, with the same read access you have in the workspace.

### API key, for headless agents

Automation cannot click a consent screen, so headless agents and CI pass a Firefight API key as a Bearer token instead. Create one under **Settings → API Keys**, then configure your client to send it.

```sh
claude mcp add --transport http firefight https://app.firefight.app/mcp \
  --header "Authorization: Bearer ff_4kWm2xPqR8vNcT6yBhJd3fLzGaU9sEnQoXwA"
```

For Cursor, put the same thing in `.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "firefight": {
      "url": "https://app.firefight.app/mcp",
      "headers": { "Authorization": "Bearer ff_4kWm2xPqR8vNcT6yBhJd3fLzGaU9sEnQoXwA" }
    }
  }
}
```

Any other MCP client works the same way, either through OAuth discovery at `/.well-known/oauth-protected-resource` or with the `Authorization: Bearer` header.

## Tools

These tools read your workspace and change nothing.

| Tool | What it returns |
|---|---|
| `search_incidents` | Incident summaries, newest first. Filter by status, severity, lifecycle stage, free-text query, and declared-at time range. |
| `get_incident` | One incident in full, by ID or identifier like `INC-42`. Details, timeline events, postmortem status, and attached alerts. |
| `search_alerts` | Ingested alerts, newest first. Each shows its source, firing status, routing state, the rule that matched, and the incident it attached to. |
| `search_catalog` | Catalog entries with their attributes and relationships, such as which team owns a service. Filter by type, name query, or exact slug. |
| `evaluate_routing` | A dry run of alert routing against hypothetical alert fields. Returns the matching rule, the outcome, and a per-condition trace. Nothing is created or notified. |
| `search_runbooks` | Runbook listings with name, summary, and step count. Filter by a name or summary query. |
| `get_runbook` | One runbook in full, by slug. The complete procedure content, ordered steps, and external link. |
| `search_approvals` | Approval requests and their status. |

### Tools that change things

These need a credential with permission to make the change, and every call is recorded.

| Tool | What it does |
|---|---|
| `upsert_catalog_entry` | Creates or updates a catalog entry |
| `delete_catalog_entry` | Removes a catalog entry |
| `upsert_routing_rule` | Creates or updates an alert routing rule |
| `delete_routing_rule` | Removes a routing rule |
| `update_routing_config` | Changes routing configuration |
| `upsert_runbook` | Creates or updates a runbook |
| `approve_approval` | Approves a pending request |
| `deny_approval` | Denies a pending request |

### Tools from your integrations

Every capability you switch on under **Configure → Integrations** also appears here, so an agent can query PlanetScale or open a Linear issue through the same connection. Nothing appears until you enable it, and who may call it is set in [Permissions](https://firefight.app/docs/api/permissions.md). See [Connect an integration](https://firefight.app/docs/api/integrations.md).

:::tip
`evaluate_routing` is a safe way to let an agent answer "what would happen if this alert fired?" It evaluates your real routing rules but never creates incidents or sends notifications.
:::

## Result caps

Search tools return 25 results by default and accept a `limit` of up to 50. When more results exist than the cap allows, the response includes a `truncated` flag set to `true`, so agents know to narrow their filters instead of assuming they saw everything. Incident timelines in `get_incident` are capped at 50 events with their own `timeline_truncated` flag. Each token may make up to 1,000 MCP requests per minute.

## Permissions

What a connected agent can query depends on the credential it authenticates with.

| Credential | Access |
|---|---|
| OAuth connection | Acts as you, with your access |
| Personal token | Acts as you, with your access |
| Service key | Only what it has been granted, and nothing by default |

Service keys map to tools by resource.

| Tool | Required permission |
|---|---|
| `search_incidents` | `incidents: read` |
| `get_incident` | `incidents: read` |
| `search_alerts` | `alerts: read` |
| `search_catalog` | `catalog: read` |
| `evaluate_routing` | `policies: read` |
| `search_runbooks` | `runbooks: read` |
| `get_runbook` | `runbooks: read` |
| `search_approvals` | `approvals: read` |
| `upsert_catalog_entry` | `catalog: create` or `catalog: update` |
| `delete_catalog_entry` | `catalog: delete` |
| `upsert_routing_rule` | `policies: create` or `policies: update` |
| `delete_routing_rule` | `policies: delete` |
| `update_routing_config` | `policies: update` |
| `upsert_runbook` | `runbooks: create` or `runbooks: update` |
| `approve_approval` | `approvals: update` |
| `deny_approval` | `approvals: update` |

A tool call without the needed permission returns an error naming the missing permission, and the agent can keep using the tools it does have. See [API overview](https://firefight.app/docs/api/overview.md) for how keys and permissions work.

## Managing connected agents

Everything connected over OAuth appears under **Settings → API Keys** in the Connected agents section, where you can revoke any connection. Revoking immediately invalidates its tokens, and the client has to go through consent again to reconnect. Agents using API keys are managed like any other key on the same page. Deactivate or delete the key to cut off the agent.