MCP server

The Bird MCP server exposes the Bird API as Model Context Protocol tools. Supported clients include Claude Code, Cursor, VS Code, Codex, Claude Desktop, ChatGPT, and Muse. They can send on every channel Bird runs, set those channels up, and inspect your workspace without copying cURL commands. You can run it in two ways, 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): tools running on your machine inside the bird CLI, for shell agents or running it yourself.

The hosted server omits these stdio-only tools:

• auth_signup, auth_verify_email, and auth_create_org: these tools create your first credential, before you can authenticate to the hosted server.
• compliance_attachments_upload: this tool reads a local file path. On the hosted server, that path would refer to the server's filesystem and could upload the wrong file.

Hosted: connect to mcp.bird.com

Choose an endpoint

Use https://mcp.bird.com for most connections. It is the recommended endpoint: most MCP clients already search and select tools internally from the full catalog. Some clients do not search tools internally, or enforce a hard limit on the number of tools a server may expose. /dynamic is for those clients.

Both hosted endpoints use Streamable HTTP and the same Bird OAuth sign-in:

The dynamic endpoint gives you access to the same hosted operations through execute. The standard endpoint and local stdio server keep their individual tools; they do not list search or execute.

You do not need to install a binary or create a token. Connecting takes two steps, and both are required:

1. Add the server: give the client your chosen endpoint URL.
2. Authenticate: sign in through your browser so the client holds a token that acts as you.

Both endpoints require authentication. A client that has only the URL receives a 401 until you sign in. Some clients start the sign-in themselves the first time they reach the server; others park the server as "needs login" and wait for you to click it. Your client's steps identify its behavior.

Use dynamic tool discovery

If your client rejects the server because it offers too many tools, connect to https://mcp.bird.com/dynamic and complete the OAuth sign-in. Your client lists two tools:

• search finds tools by name or description keywords. Each match includes its name, description, input schema, and annotations describing whether it reads or changes data.
• execute calls one selected tool with its arguments. It can read data, send messages, change records, or delete them, depending on the selected tool.

For example, your agent can find the workspace tool with this tool call:

{
  "name": "search",
  "arguments": { "query": "workspace_get", "limit": 3 }
}

After reading the returned input schema, it calls that tool through execute:

{
  "name": "execute",
  "arguments": { "tool": "workspace_get", "arguments": {} }
}

The result contains your current workspace. You can also search with task keywords such as send email. Search defaults to five matches, accepts a limit from one through 10, and accepts queries up to 500 characters. If the result has has_more: true, narrow your query to find more relevant matches.

Search results do not add tools to your client's catalog. Names mentioned in results or recovery instructions also go through execute. Execution uses your existing permissions; if an operation needs more permissions, your client may ask you to authorize them. Finding a tool does not grant access to it.

Dynamic execution returns data for tools that otherwise display widgets. Use the standard endpoint for interactive MCP Apps widgets. Clients see one execution tool, so per-tool approval settings apply to execute as a whole; check the selected operation before approving a call. This endpoint executes tool calls and does not run JavaScript or other supplied code.

Connect a client

The examples below use the standard endpoint. For dynamic discovery, substitute https://mcp.bird.com/dynamic as the server URL and follow the same sign-in steps.

Claude Code

Add the server:

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

claude mcp list now reports bird as ! Needs authentication. Claude Code does not open the browser on its own, so sign in from inside a session:

1. Run /mcp.
2. Select bird and press Enter.
3. Choose Authenticate. Your browser opens Bird's consent screen; approve it there.

The server then reads as connected and the tools work. A headless run (claude -p) has no /mcp panel, so authenticate first from your shell with claude mcp login bird. To sign in again later, /mcp offers Re-authenticate; Clear authentication drops the stored token.

Installing the bird-ai plugin declares this server for you, which replaces the claude mcp add command. Authentication is still required because a plugin can ship a server but cannot issue a grant. Select /mcp > bird > Authenticate after installing it.

Cursor

In ~/.cursor/mcp.json:

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

Then open Customize in the Cursor sidebar and select MCPs. Find bird, follow its sign-in prompt, approve Bird's consent screen in the browser, and return to Cursor.

OpenCode

Bird's OpenCode plugin registers the server for you, together with Bird's agent skills:

opencode plugin github:messagebird/bird-ai --global

OpenCode adds every MCP tool to the model's context, so the plugin connects to the dynamic endpoint. With OpenCode's experimental code mode on (OPENCODE_EXPERIMENTAL_CODE_MODE=1, or OPENCODE_EXPERIMENTAL=1), OpenCode keeps MCP tools behind its own search, and the plugin connects to the full catalog at https://mcp.bird.com instead.

To add the server without the plugin, put this in opencode.json, in your project or at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bird": {
      "type": "remote",
      "url": "https://mcp.bird.com/dynamic"
    }
  },
  "permission": {
    "bird_execute": "ask"
  }
}

Then sign in, which opens your browser for Bird's consent screen:

opencode mcp auth bird

Restart OpenCode to load the plugin. opencode mcp list reports bird as connected once you approve. The plugin, like the permission entry above, makes OpenCode ask before each execute call, because the tool it runs can change your workspace.

VS Code

In .vscode/mcp.json in your project:

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

Using settings.json instead? Put the same bird entry under mcp.servers. VS Code moves it into your user mcp.json, which MCP: Open User Configuration opens:

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

VS Code asks you to trust the server the first time it starts, then runs the OAuth flow itself: approve Bird's consent screen in the browser window it opens. If no window appears, start or restart bird from the MCP: List Servers command and approve it then. The resulting grant is listed under Accounts > Manage Trusted MCP Servers, which is also where you revoke VS Code's access.

Codex

In ~/.codex/config.toml:

[mcp_servers.bird]
url = "https://mcp.bird.com"

Then sign in from your shell, which opens the browser:

codex mcp login bird

Claude Desktop

Open Customize > Connectors, click +, then Add custom connector. Paste https://mcp.bird.com and click Add. Then click Connect on the Bird connector to run the sign-in and approve the consent screen. On Team and Enterprise plans an owner adds the connector once from Organization settings > Connectors, and each member still clicks Connect under Customize > Connectors for their own grant. Turn the connector on per conversation from + > Connectors.

ChatGPT

Custom MCP apps need developer mode: open Settings > Security and login and turn on Developer mode. Then go to ChatGPT Plugins, select +, and create a developer-mode app: give it a name, paste https://mcp.bird.com, and pick OAuth as the authentication. ChatGPT runs the sign-in itself and opens Bird's consent screen. In a conversation, choose Developer mode from the + menu and select Bird.

Muse

Muse adds Bird as a custom connector. In a Muse chat, ask it to set one up:

Set up a custom connector to the Bird MCP server at https://mcp.bird.com following https://bird.com/docs/ai/mcp-server.md so you can work with my Bird workspace.

Muse replies with a connection link for this session. Open it and approve Bird's consent screen in the browser. The link works only for you and expires with the session. If it stops working, ask Muse for a new one.

Factory Droid

droid mcp add bird https://mcp.bird.com --type http

Then run /mcp inside droid and complete the browser sign-in from the server manager.

Antigravity

Bird's Antigravity plugin registers the server for you, together with Bird's agent skills:

curl -fsSL https://raw.githubusercontent.com/messagebird/bird-ai/main/antigravity.sh | bash

To add the server without the plugin, put this in ~/.gemini/config/mcp_config.json, or in .agents/mcp_config.json for one project. Antigravity reads a remote server's address from serverUrl, so keep that key name:

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

Then sign in: open Customizations in the sidebar (in the IDE, open Agent settings with Cmd+, on macOS or Ctrl+, on Windows and Linux), and select Authenticate next to bird. If bird is not listed, restart Antigravity. Approve Bird's consent screen in the browser, copy the authorization code it shows, paste it into Antigravity, and select Submit.

Agent Plugins

The bird-ai plugin declares this server in an mcp.json that follows Agent Plugins. A host that implements the specification reads that file when the plugin installs, so there is no server config to write: install the plugin and sign in.

Any other host

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. The field location varies; use your chosen hosted endpoint URL. Then find that client's sign-in affordance: a Connect, Authorize, or Needs login control beside the server, a login subcommand, or a browser window the client opens by itself. A client that lists Bird's tools but fails every call has the URL but still needs a grant.

What happens when you sign in

Your browser opens to a Bird consent screen. Sign in, choose whether to grant workspace or organization permissions, and select which 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, so this is a one-time step per client.

The quickest way to prove it worked is to have the agent call whoami: it returns the signed-in user, so a real answer means the grant is in place. On the dynamic endpoint, call it through execute with tool: "whoami" and empty arguments.

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 flow uses standard MCP. Clients differ only in what triggers it: the first tool call or selecting Authenticate. After the flow starts, the authentication steps need no extra configuration:

1. 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).
2. From there it discovers the authorization server, then registers itself dynamically (RFC 7591). Dynamic registration removes the need for a pre-shared client ID or manual configuration.
3. Your browser opens Bird's consent screen.
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

Run the local MCP server inside the bird CLI for shell-capable agents or access to files on your machine. 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). This path needs no per-client sign-in because bird auth login already holds the grant.

Cursor

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

VS Code

In .vscode/mcp.json in your project:

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

Claude Code

claude mcp add bird -- bird mcp

How the local server authenticates

The local server acts as you and reuses the CLI's stored login. bird auth login opens a browser OAuth flow where you grant a subset of your workspace permissions. The issued token has the hosted grant's permission caps. Neither org:owner nor platform-admin scopes are available. bird mcp reads and refreshes the stored login from the CLI credentials file, whose mode is 0600. As with the hosted tier, your client configuration has no BIRD_API_KEY or other secret. If the login is missing, bird mcp refuses to start and tells you to run bird auth login.

You do not expose a listener: 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 spans every channel Bird runs, plus the account and configuration tasks around them. It is curated rather than the full API surface: each tool is scoped to a task an agent actually performs, and destructive operations are annotated so hosts can ask before running them.

Email has the most tools, because it has the most surface to configure. The other channels carry the same send-and-read shape.

Messaging

• Send and inspect email: email_send, email_send_batch, email_list, and email_get, which returns the message with its aggregate delivery status. Per-recipient delivery statuses and the event log are separate tool calls.
• Send and inspect SMS: sms_send, sms_send_batch, sms_get, sms_list, and sms_list_events, mirroring the email shape. sms_templates_list and sms_templates_get read the template catalog.
• Send and inspect WhatsApp: whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events, and whatsapp_media. Templates are a full authoring surface under whatsapp_templates_*, including per-version and per-language content.
• Inspect voice call legs: voice_legs_get and voice_legs_list read call legs, with per-country and per-response-code statistics under voice_stats_*. voice_session_credentials_create creates the workspace credential a SIP or softphone client uses to authenticate.
• Verify a recipient: verify_verifications_create sends a one-time passcode, verify_verifications_check validates what the recipient submitted, and verify_verifications_next_channel falls back to another channel.
• Create a voice call (preview): voice_calls_create prepares an outbound call using the active publication of an enabled, unarchived sequence. A person reviews and runs the request in the browser; preparing it does not place the call. See Create a voice call for permissions and retry instructions. The local bird mcp server requires a CLI version that includes this tool.

Getting a channel ready to send

• Set up sending domains: email_domains_create adds a sending domain and returns the DNS records to publish; email_domains_verify re-checks them; plus email_domains_list and email_domains_get.
• Claim and register SMS senders: sms_senders_create claims a sender, sms_senders_requirements reports what a country demands of it, and sms_senders_registrations_create registers it. US A2P traffic runs through the sms_10dlc_* brand, campaign, and submission tools.
• Provision numbers: numbers_available_list searches, numbers_orders_create buys, and numbers_release gives back. whatsapp_numbers_precheck reports whether WhatsApp will accept a number before you order it.
• Check the account can send at all: the trust_* tools report the organization requirements that gate buying a number or registering a sender.

Email deliverability

• Author email templates: email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate, and email_templates_preview (render a draft with sample values without sending). Versions live under email_templates_versions_*, where email_templates_versions_submit freezes a draft and makes it the version sends serve, and email_templates_versions_languages_* edits a draft's per-language content. Nothing an agent writes reaches a recipient until it submits.
• Manage suppressions: email_suppressions_list, email_suppressions_check (is this address safe to send to?), email_suppressions_add, and email_suppressions_remove (annotated destructive, because removing a suppression without a reason damages sender reputation).
• Manage dedicated IPs and pools: email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (move one into a pool), and email_dedicated_ips_delete; plus email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update, and email_ip_pools_delete for the pools you route sends through.

Audience and configuration

• Manage contacts and audiences: contacts_* and contact_properties_* for the people you send to, audiences_* for the lists you send to, and preferences_* for consent grants and opt-outs.
• Provision Realtime: realtime_apps_* and realtime_apps_keys_* create the apps and keys the Realtime clients connect with.
• Look someone up: lookup_phone_number and lookup_email report what Bird knows about an address before you send to it.
• Inspect configuration: webhooks_list, workspace_get, and whoami (the signed-in user: id, email, name).

Your client shows the live tool list with names, descriptions, and input schemas. Treat that listing as 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

• MCP Events: subscribe your client to Bird events, such as new mail in a mailbox, and receive each one as a signed webhook.
• Query email analytics with AI: ask about delivery, engagement, and latency in plain language.
• 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.