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.platform.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.platform.bird.com

The hosted server speaks Streamable HTTP at a single endpoint:

Contoh kode

https://mcp.platform.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:

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) — no pre-shared client ID, nothing for you to configure.
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.
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 the dashboard's connected-apps list, 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, which installs the skills and wires up this server in one step; the manual config for each client is below.

Claude Code

Contoh kode

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

Cursor

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

Contoh kode

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

VS Code

In .vscode/mcp.json in your project:

Contoh kode

{
  "servers": {
    "bird": {
      "type": "http",
      "url": "https://mcp.platform.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.platform.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. Install the CLI and sign in, then serve MCP over stdio:

Contoh kode

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

Contoh kode

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

VS Code

Contoh kode

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

Claude Code

Contoh kode

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 — setup_domain returns the DNS records to publish; verify_domain re-checks them; plus list_domains and get_domain.
Inspect configuration — list_webhooks and get_workspace.

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:

Send a test email from onboarding@messagebird.dev to delivered@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.

Go deeper

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.