MCP server

The Bird MCP server exposes the Bird API as Model Context Protocol 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:

Hosted (mcp.bird.com): a URL and a browser sign-in. Nothing to install, no CLI, no API key. This is the recommended path.
Local over stdio (bird mcp): the same tools running on your machine inside the bird CLI, 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):

Ejemplo de código

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

VS Code

In .vscode/mcp.json in your project:

Ejemplo de código

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

Claude Code

Ejemplo de código

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

Or install the bird-ai plugin, 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 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:

The client makes an unauthenticated request and gets back 401 with a WWW-Authenticate header pointing at Bird's RFC 9728 protected-resource metadata (/.well-known/oauth-protected-resource).
From there it discovers the authorization server, then registers itself dynamically (RFC 7591), so there is no pre-shared client ID and nothing for you to configure.
Your browser opens to the consent screen described above.
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: useful offline, for shell-capable agents, or when you'd rather run the process yourself. Install the CLI, 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

Ejemplo de código

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

VS Code

Ejemplo de código

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

Claude Code

Ejemplo de código

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 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: the quickstart version of this page, plus the machine-readable docs corpus.
Agent skills: the bird-ai marketplace plugin, skills plus this MCP server, installed in one step.
CLI for agents: drive Bird from shell-capable agents without MCP: JSON output, semantic exit codes, OAuth login.
Authentication: API keys, regions, and how requests are authorized.