# MCP server (connect Brizz to your AI tools)

Expose Brizz as an MCP server so Claude Code, Claude Desktop, Cursor, Codex, and other AI agents can query your data.

This page is about **connecting Brizz to your AI agent** so it can query Brizz on your behalf. If instead you want to **add Brizz observability to an MCP server you operate**, see [MCP (auto-instrument your server)](/docs/sdks/mcp.md).

Talk to your Brizz data from inside Claude Code, Claude Desktop, Cursor, Codex, and any other AI agent that speaks the Model Context Protocol. Ask things like "what issues showed up today?", "summarize the worst session", or "which services are slowest" — your agent calls Brizz directly and answers from real data.

You sign in once with your Brizz account — no API key to copy, store, or rotate. If your client can't complete an interactive sign-in (headless setups, scripts), use a [Platform API key](#platform-api-key) instead.

## Server URL

```
https://platform.brizz.dev/mcp
```

Paste this URL (or the snippet for your agent below) into your AI tool. The first time the agent uses a Brizz tool, your browser opens to sign you in — same login you use for the dashboard.

## Set up your agent

Pick your client below for the interactive sign-in flow. For a headless client, script, or CI that can't open a browser, use a [Platform API key](#platform-api-key) instead.

:::tabs
:::tab[Claude Code]
Run this from your terminal — any directory works.

```bash
claude mcp add --transport http brizz https://platform.brizz.dev/mcp
```

Type `/mcp` inside Claude Code anytime to manage the connection or sign in again.
:::tab[Claude Desktop]
Open Claude Desktop's config file and add the snippet below, then restart the app.

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "brizz": {
      "url": "https://platform.brizz.dev/mcp"
    }
  }
}
```
:::tab[Cursor]
Add the snippet to `~/.cursor/mcp.json` for global access, or to `.cursor/mcp.json` inside a project to scope it. Cursor will prompt you to sign in the first time the agent calls Brizz.

```json
{
  "mcpServers": {
    "brizz": {
      "url": "https://platform.brizz.dev/mcp"
    }
  }
}
```
:::tab[Codex / VS Code / Cline]
Run the Codex CLI command — the same JSON shape works for VS Code Continue and Cline too.

```bash
codex mcp add brizz --url https://platform.brizz.dev/mcp
```

```json
{
  "mcpServers": {
    "brizz": {
      "transport": "http",
      "url": "https://platform.brizz.dev/mcp"
    }
  }
}
```
:::tab[Other clients]
Any MCP client that supports streamable HTTP can connect — just point it at the server URL above.

If your client needs a metadata URL for discovery, use:

```
https://platform.brizz.dev/.well-known/oauth-protected-resource
```
:::

## Authentication

Your agent connects with your own Brizz identity: tools run with your role and your tenant, nothing is exposed across tenants, and the agent never sees your password. Pick whichever method your client supports.

### Interactive sign-in (default)

Interactive clients — Claude Code, Claude Desktop, Cursor, Codex — sign you in through your browser the first time the agent calls a Brizz tool, using the same login as the dashboard. There's no API key to copy, store, or rotate; tokens are short-lived and refreshed automatically by your client. Sign out of Brizz anytime to invalidate the session.

### Platform API key

Headless clients, scripts, and CI that can't complete an interactive sign-in can authenticate with a **Platform API key** instead.

1. Create a key under [**User Settings > Platform API Keys**](/app/settings/platform-api-keys). Copy it — it's shown once.
2. Pass it as a bearer token when connecting:

```bash
claude mcp add --transport http brizz https://platform.brizz.dev/mcp --header "Authorization: Bearer <key>"
```

For clients configured via JSON, add the header alongside the URL:

```json
{
  "mcpServers": {
    "brizz": {
      "url": "https://platform.brizz.dev/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}
```

The key acts with your role and tenant, same as signing in interactively. Revoke it anytime from [**User Settings > Platform API Keys**](/app/settings/platform-api-keys).

## What your agent can do

Your agent sees every Brizz tool by name and picks the one that fits — no setup, no discovery step. Modern clients load tool definitions only when they're used, so a full tool list costs nothing until it's needed.

If your token is read-only, the tools that change data aren't listed at all — the agent can browse and analyze, but not modify.

| Capability | What it does |
| --- | --- |
| Confirm identity | Which user, tenant, and role the agent is acting as. |
| Search & read sessions | Find conversation sessions by filter, fetch one by id, or pull every turn (messages + tool calls) of a conversation. |
| Search & manage issues | Find quality issues by status / priority / severity, fetch one by id, or change its status, priority, or assignment. |
| Query metrics | Return a time-bucketed metric series to chart. |
| Explore organizations | List your organizations and get a health-and-activity summary. |
| Discover what's filterable | The metric catalog, issue enums, intent labels, custom-property keys (e.g. `plan_tier`, `account_id`), and the fields each search accepts. |
| List services | The monitored trace services for your tenant. |
| Multi-turn analysis | Continue an analytics conversation with the Brizz agent across turns. |
| Ask the analyst | Hand an open-ended "why" question to the Brizz analytics agent when no direct tool answers it. |
| Follow a runbook | Load a step-by-step investigation guide — diagnose a session, root-cause an issue, triage a service, chase a cost spike. |

For the full reference — every tool, its arguments, and its allowed values — see [MCP server tools](/docs/integrations/mcp-server/tools.md).

## Investigate an issue from the dashboard

Once your agent is connected, you don't have to write the investigation prompt yourself. On any issue, open **Fix with your agent** and pick the **Brizz MCP** tab. It shows the `brizz_investigate_issue` call for that issue with `service_name` and `issue_id` already filled in — copy it, paste it into your agent, and the agent fetches the handoff document itself.

Anything you type into **Add context for the agent** rides along as the call's `notes` argument, so a hypothesis or a user complaint reaches the investigation without a second message.

The document your agent receives ends in `next-tool-calls` blocks — follow-up MCP calls already scoped to that issue — rather than the shell commands the Manual and Brizz CLI tabs hand out.

If your agent replies that it has no Brizz tools, expand **Not connected to Brizz MCP yet?** in the same tab for the server URL, or finish setup under [**Settings > Integrations**](/app/settings/integrations).

## Troubleshooting

**The agent says it can't reach Brizz.**
Check that you ran the setup command for *your* Brizz workspace — the URL above is generated for the workspace you're currently signed into.

**Sign-in popup never appears.**
Some clients only sign you in the first time a tool runs. Try asking the agent something simple like *"list my Brizz services"* to trigger the flow.

**I want to disconnect.**
Remove the `brizz` entry from your client's MCP config (or run the client's equivalent of `mcp remove brizz`). You can also sign out of Brizz in the dashboard to immediately invalidate the connection.

## See also

- [MCP server tools](/docs/integrations/mcp-server/tools.md) — the full tool reference: every tool, its arguments, and its allowed values.
- [MCP (auto-instrument your server)](/docs/sdks/mcp.md) — the *other* MCP page: instrumenting an MCP server you operate, not connecting agents to Brizz.
- [API keys](/docs/admin/api-keys.md) — the telemetry API keys used to ingest data into Brizz, distinct from the Platform API keys used above to connect the MCP server.
- [Troubleshooting](/docs/help/troubleshooting.md) — sign-in issues and connection diagnostics.