# 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`)** — 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`)** — 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`

The hosted server speaks **Streamable HTTP** at a single endpoint:

```text
https://mcp.bird.com
```

Point a remote-capable MCP client at that URL and it connects — no binary to install, no token to generate. The server is stateless and regional traffic is routed automatically, so the one URL works from anywhere.

### How it authenticates

There is **nothing to paste**. The hosted tier 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 and which is scoped to exactly the workspace and permissions you approved.

Your client obtains that token through the standard MCP browser sign-in, and the whole handshake is 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)) — no pre-shared client ID, nothing for you to configure.
3. Your browser opens to a Bird consent screen. You sign in (if you aren't already), pick the workspace or organization to grant, and choose which of your permissions to delegate. Because the client registered itself, its name is self-asserted, so the screen flags it as **not verified by Bird** — confirm it's the client you actually launched before approving.
4. The client exchanges the result for an access token (PKCE; refreshed automatically) and the Bird tools appear.

The granted token 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. The grant shows up in your profile's [**Connected apps**](https://bird.com/dashboard/profile/connected-apps) list in the dashboard, and revoking it there cuts the client off immediately.

### Connect a client

The hosted server works with any client that supports remote (HTTP) MCP servers. The fastest path on Claude Code is the [bird-ai plugin](/docs/ai/agent-skills), which installs the skills **and** wires up this server in one step; the manual config for each client is below.

#### Claude Code

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

#### 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 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`. The browser sign-in runs the first time the client connects.

The first time a client connects it runs the OAuth flow above; after that the Bird tools appear in the agent's tool list and the token refreshes silently.

## Local: run it over stdio with the CLI

If you need an offline server, want a shell-capable agent to host it, or would rather run the process yourself, the same toolset ships inside the [`bird` CLI](/docs/ai/cli-for-agents). Install the CLI and sign in, then serve MCP over stdio:

```bash
bird auth login
bird mcp
```

It speaks MCP over **stdio**: your MCP client launches the process and talks to it on stdin/stdout. 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 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`. The API host follows your login's region automatically; `--base-url` (or `BIRD_API_URL`) overrides it for testing against a non-production environment.

Every MCP client takes 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
```

## 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 — 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.