In September we announced that Bird's communications infrastructure is open to AI agents. This post is the developer's version of that announcement. It names the commands an agent runs, what it connects to, how it gets an account, and the limits you can put on it, each with the page that documents it.
The CLI
An agent that can run shell commands, such as Claude Code, Cursor's terminal, or a CI job, should start with the CLI: it uses far fewer tokens for each operation than MCP does. The MCP server, described next, is for hosts that call tools and cannot run a shell, and for MCP Events.
bird is a single binary built to be driven by an agent. Output is JSON on stdout, errors go to stderr, and the exit code carries the failure category, so an agent can branch on the result without parsing prose.
Three flags do most of the work for an agent. --example prints a valid request body, --dry-run shows the request without sending it, and --idempotency-key makes a retry safe when a response is lost. CLI for agents describes the contract, and the CLI reference lists each command.
The hosted MCP server
Some hosts call tools and cannot run a shell, such as Claude Desktop, ChatGPT, or a mobile app. For those, the Bird MCP server runs at https://mcp.bird.com. Give that URL to an MCP client and sign in through your browser, and the client holds a token that acts as you. The consent screen shows the permissions the client asks for, and you can clear the ones the agent does not need. You install nothing and copy no API key. Supported clients include Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT, and Muse, and Bird is listed in Claude's connector directory.
The server exposes the Bird API as tools, so a connected agent can send on the channels Bird runs, set those channels up, and inspect your workspace. A client with a limit on the number of tools can connect to https://mcp.bird.com/dynamic, which lists two tools: search finds an operation and execute calls it. With MCP Events, a client
MCP server has the steps for each client. Once the CLI is installed, bird mcp runs a local server over stdio. It adds the signup tools and uploads from local files, and it does not serve MCP Events.
Signup from a terminal
An agent that has no account can create one from a terminal, with no browser session and no dashboard visit. It needs access to an email inbox, because the sign-in code arrives by email:
bird auth create-org creates the organization and its workspace, and stores a credential that the CLI and the local MCP server use from then on. --region chooses where the account and its data live, us1 or eu1. The same three steps work with curl, for an agent that has no CLI. The hosted MCP server does not offer signup, because a client needs a credential before it can connect there.
That first credential is broad. It holds the permissions the new organization's owner can delegate, organization billing included, and signup shows no consent screen to narrow it. Before an agent runs unattended, create a scoped API key for it. Self-serve signup walks through both paths.
Controls on what an agent can do
An agent that sends through Bird holds a credential and spends your balance. Agent controls documents on one page what bounds it. These are the four to set before an agent runs unattended. The destination allowlist and the daily spend limit apply to SMS. Email and WhatsApp have neither, so the key's scopes and the wallet are what bound an agent there. The same page covers safe retries: send an Idempotency-Key header, or --idempotency-key on the CLI, and a repeated request is accepted once.
Scoped API keys. An API key belongs to one workspace and carries the scopes you give it, each a product area at read or write level. A key that sends SMS and does nothing else holds sms:write, and a request outside its scopes returns 403. A key cannot issue another key, and it cannot reach billing.
The sign-in must hold api_keys:write and the scopes the key will carry. The credential from terminal signup already holds them, so after bird auth create-org you run the second command alone. Do not sign in again there: a new sign-in replaces the signup credential. Run it in a shell where BIRD_API_KEY is not set, because the CLI uses that key in preference to a sign-in, and a key cannot issue keys.
Then give the agent the key and nothing wider. Set BIRD_API_KEY in the agent's environment, or send the key as a bearer token from your code. A sign-in stays stored on the machine where it ran, and an agent there with no BIRD_API_KEY uses it. Run the agent somewhere else, or remove the sign-in with bird auth logout.
Default-deny SMS destinations. A workspace sends SMS to the countries on its destination allowlist. The allowlist starts empty, and Bird adds your organization's home country when it is set. A send through the SMS API to any other country is rejected with 422 SMSDestinationNotEnabled before a sender is resolved, so an agent pointed at an unexpected country is refused. Verification codes do not use this list. Verify has its own, where every country starts enabled, and Voice has its own settings too.
Daily spend limits. Each SMS destination country can carry a daily spend limit, in your wallet's currency. Once the day's spend to that country reaches the limit, Bird refuses new messages there until midnight UTC. The limit is not exact: spend counts when a message is charged, so messages already accepted can take the day's total past it. Verification codes sent by SMS count toward the limit. This command enables the Netherlands with a limit of 25 EUR a day, in a workspace whose wallet is in EUR:
Changing the allowlist or a limit needs the sms_management scope at write level. Give the sending agent sms, keep sms_management for the credential that configures the workspace, and the agent cannot raise its own limits.
The prepaid wallet. Pay-as-you-go sends draw on your organization's prepaid wallet. An SMS send that the balance cannot cover is refused with 402. Some charges settle after a send is accepted (email on a paid Email plan, and fees charged at delivery), and automatic top-up refills the wallet from a saved card, so read the wallet rules before you treat the balance as a hard cap. Billing operations need the organization's billing permission, which an API key cannot hold. Give an unattended agent a scoped key, and adding funds stays with the people who own the budget.
Where to go next
- Give an agent its own phone number and inbox: an inbox.ai address and a dedicated number that both send and receive. Before the first number, a person funds the wallet and an organization owner completes identity verification. The guide says which steps of an order need a person.
- Bird for European customers: the Dutch entity you contract with, the eu1 region, and the Data Processing Agreement.
- Send Supabase Auth SMS codes with Bird: phone sign-in codes for a Supabase project, sent through the Bird SMS API.
- Set up your coding agent: paste one prompt, and your agent installs the CLI and Bird's skills.











