# MCP server

The Bird MCP server exposes the Bird API as [Model Context Protocol](https://modelcontextprotocol.io) tools, so any MCP-aware client (Cursor, VS Code, Claude Code, Claude Desktop, ChatGPT) can send email, manage domains, and inspect your workspace through Bird directly instead of you copy-pasting curl commands. There are two ways to run it, and most people want the first:

1. **[Hosted (`mcp.bird.com`)](#hosted-connect-to-mcpbirdcom)**: a URL and a browser sign-in. Nothing to install, no CLI, no API key. This is the recommended path.
2. **[Local over stdio (`bird mcp`)](#local-run-it-over-stdio-with-the-cli)**: the same tools running on your machine inside the [`bird` CLI](/docs/ai/cli-for-agents), for offline use, shell agents, or running it yourself.

Both serve the identical curated toolset; they differ only in where the process runs and how it authenticates.

## Hosted: connect to `mcp.bird.com`

Point any client that supports remote MCP servers at `https://mcp.bird.com`. There is no binary to install and no token to create. The first connection opens a browser for you to sign in and pick a workspace.

### Connect a client

If your client isn't listed below, look for the setting that adds a **remote**, **HTTP**, or **custom** MCP server, often under a Connectors or Integrations menu, and give it the URL. Clients differ in where the field lives, not in what they need: the URL is the whole configuration.

#### Cursor

In `~/.cursor/mcp.json` (or **Settings → MCP**):

```json
{
  "mcpServers": {
    "bird": {
      "url": "https://mcp.bird.com"
    }
  }
}
```

#### VS Code

In `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "bird": {
      "type": "http",
      "url": "https://mcp.bird.com"
    }
  }
}
```

#### Claude Code

```bash
claude mcp add --transport http bird https://mcp.bird.com
```

Or install the [bird-ai plugin](/docs/ai/agent-skills), which wires up this server and the Bird skills in one step.

#### Claude Desktop, ChatGPT, and other hosts

Any client with a "custom connector" or "add remote MCP server" field takes the same URL: `https://mcp.bird.com`.

### What happens on first connect

Your browser opens to a Bird consent screen. Sign in, pick the workspace or organization to grant, and choose which of your permissions to delegate. Because MCP clients register themselves, the client's name is self-asserted, so the screen flags it as **not verified by Bird**. Confirm it's the client you actually launched before approving. After that the tools appear in the agent's list and the token refreshes silently.

The grant is capped to the intersection of what the client requested, what you approved, and what you actually hold; `org:owner` and platform-admin scopes are never delegable. It appears in your profile's [**Connected apps**](https://bird.com/dashboard/profile/connected-apps) list, and revoking it there cuts the client off immediately.

### How the handshake works

You don't need this to connect a client. It matters if you're debugging a client that won't authenticate, or writing one.

The hosted tier speaks **Streamable HTTP** and is credential-less: it stores no secrets and validates nothing itself. Each request carries your own OAuth bearer token, which Bird's API validates per request. The server is stateless and regional traffic is routed automatically, so the one URL works from anywhere.

The sign-in is the standard MCP flow, entirely automatic:

1. The client makes an unauthenticated request and gets back `401` with a `WWW-Authenticate` header pointing at Bird's [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata (`/.well-known/oauth-protected-resource`).
2. From there it discovers the authorization server, then **registers itself dynamically** ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)), so there is no pre-shared client ID and nothing for you to configure.
3. Your browser opens to the consent screen described above.
4. The client exchanges the result for an access token (PKCE; refreshed automatically) and the Bird tools appear.

## Local: run it over stdio with the CLI

The same toolset ships inside the [`bird` CLI](/docs/ai/cli-for-agents): useful offline, for shell-capable agents, or when you'd rather run the process yourself. [Install the CLI](/docs/cli#install), run `bird auth login` once, then point your client at the `bird mcp` command.

You don't run `bird mcp` yourself: your client launches it and talks to it on stdin/stdout. Every client needs the same two facts: the command (`bird`) and the argument (`mcp`).

#### Cursor

```json
{
  "mcpServers": {
    "bird": {
      "command": "bird",
      "args": ["mcp"]
    }
  }
}
```

#### VS Code

```json
{
  "servers": {
    "bird": {
      "command": "bird",
      "args": ["mcp"]
    }
  }
}
```

#### Claude Code

```bash
claude mcp add bird -- bird mcp
```

### How the local server authenticates

The local server acts as **you**, reusing the CLI's stored login. `bird auth login` runs a browser OAuth flow where you pick one workspace and a subset of your own permissions; the issued token is capped the same way the hosted flow caps it, and `org:owner` and platform-admin scopes are never grantable. `bird mcp` reads that stored login (the same credentials file as every other `bird` command, mode `0600`) and refreshes it silently, so, as with the hosted tier, there's no `BIRD_API_KEY` and no secret in your client config. If the login is missing, `bird mcp` refuses to start and tells you to run `bird auth login`.

There is no listener to expose: the server runs on your machine, inside the client's sandbox, for exactly as long as the client needs it. The API host follows your login's region automatically; `--base-url` (or `BIRD_API_URL`) overrides it for testing against a non-production environment.

## What the tools cover

The toolset is hand-curated rather than generated from the API spec. Each tool is scoped to a task an agent actually performs, and destructive operations are annotated so hosts can ask before running them:

- **Send and inspect email**: `send_email`, `send_email_batch`, `list_emails`, and `get_email`, which returns the message, its per-recipient delivery statuses, and the event log in one call.
- **Manage suppressions**: `list_suppressions`, `check_suppression` (is this address safe to send to?), `add_suppression`, and `remove_suppression` (annotated destructive, because removing a suppression without a reason damages sender reputation).
- **Set up sending domains**: `create_domain` adds a sending domain and returns the DNS records to publish; `verify_domain` re-checks them; plus `list_domains` and `get_domain`.
- **Manage dedicated IPs and pools**: `create_dedicated_ip`, `list_dedicated_ips`, `get_dedicated_ip`, `assign_dedicated_ip` (move one into a pool), and `delete_dedicated_ip`; plus `create_ip_pool`, `list_ip_pools`, `get_ip_pool`, `update_ip_pool`, and `delete_ip_pool` for the pools you route sends through.
- **Inspect configuration**: `list_webhooks`, `get_workspace`, and `whoami` (the signed-in user: id, email, name).

Your client shows the live tool list with names, descriptions, and input schemas. That listing, not this page, is the authoritative inventory. A good first task to try end to end:

> Call `whoami` to find my email, then send me a test email from onboarding@messagebird.dev and tell me when it's delivered.

## MCP or the CLI?

Same surface, same auth model, different callers. For shell-capable agents (Claude Code, Cursor's terminal, CI), the [CLI](/docs/ai/cli-for-agents) is leaner: JSON output, semantic exit codes, and far fewer tokens per operation. MCP is for hosts that call tools instead of running shells, and the hosted endpoint reaches the ones that can't exec a binary at all (Claude Desktop, ChatGPT, mobile). You don't have to choose up front: the hosted URL needs no install, and the local `bird mcp` is already there once the CLI is.

## Next steps

- [AI onboarding](/docs/get-started/ai-onboarding): the quickstart version of this page, plus the machine-readable docs corpus.
- [Agent skills](/docs/ai/agent-skills): the bird-ai marketplace plugin, skills plus this MCP server, installed in one step.
- [CLI for agents](/docs/ai/cli-for-agents): drive Bird from shell-capable agents without MCP: JSON output, semantic exit codes, OAuth login.
- [Authentication](/docs/guides/authentication): API keys, regions, and how requests are authorized.