Servidor MCP

O servidor Bird MCP expõe a Bird API como ferramentas do Model Context Protocol. Os clientes compatíveis incluem Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT e Muse. Eles podem enviar por todos os canais que a Bird opera, configurar esses canais e inspecionar seu espaço de trabalho sem copiar comandos cURL. Você pode executá-lo de duas formas, e a maioria das pessoas prefere a primeira:

1. Hospedado (mcp.bird.com): uma URL e login pelo navegador. Nada para instalar, sem CLI, sem chave API. Este é o caminho recomendado.
2. Local via stdio (bird mcp): ferramentas rodando na sua máquina dentro do bird CLI, para agentes de shell ou execução por conta própria.

O servidor hospedado omite estas ferramentas exclusivas do stdio:

• auth_signup, auth_verify_email e auth_create_org: essas ferramentas criam sua primeira credencial, antes de você poder se autenticar no servidor hospedado.
• compliance_attachments_upload: essa ferramenta lê um caminho de arquivo local. No servidor hospedado, esse caminho se referiria ao sistema de arquivos do servidor e poderia enviar o arquivo errado.

Hospedado: conecte-se ao mcp.bird.com

Escolha um endpoint

Use https://mcp.bird.com para a maioria das conexões. É o endpoint recomendado: a maioria dos clientes MCP já busca e seleciona ferramentas internamente a partir do catálogo completo. Alguns clientes não buscam ferramentas internamente ou impõem um limite rígido ao número de ferramentas que um servidor pode expor. /dynamic é para esses clientes.

Ambos os endpoints hospedados usam Streamable HTTP e o mesmo login Bird OAuth:

O endpoint dinâmico dá acesso às mesmas operações hospedadas por meio de execute. O endpoint padrão e o servidor stdio local mantêm suas ferramentas individuais; eles não listam search nem execute.

Você não precisa instalar um binário nem criar um token. A conexão exige dois passos, e ambos são obrigatórios:

1. Adicione o servidor: forneça ao cliente a URL do endpoint escolhido.
2. Autentique-se: faça login pelo navegador para que o cliente tenha um token que age como você.

Ambos os endpoints exigem autenticação. Um cliente que tem apenas a URL recebe um 401 até você fazer login. Alguns clientes iniciam o login sozinhos na primeira vez que acessam o servidor; outros deixam o servidor como "needs login" e esperam você clicar. Os passos do seu cliente indicam o comportamento dele.

Use a descoberta dinâmica de ferramentas

Se seu cliente rejeitar o servidor por oferecer ferramentas demais, conecte-se a https://mcp.bird.com/dynamic e conclua o login OAuth. Seu cliente lista duas ferramentas:

• search encontra ferramentas por nome ou palavras-chave da descrição. Cada resultado inclui nome, descrição, schema de entrada e anotações indicando se a ferramenta lê ou altera dados.
• execute chama uma ferramenta selecionada com seus argumentos. Pode ler dados, enviar mensagens, alterar registros ou excluí-los, dependendo da ferramenta selecionada.

Por exemplo, seu agente pode encontrar a ferramenta de espaço de trabalho com esta chamada de ferramenta:

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

Depois de ler o schema de entrada retornado, ele chama essa ferramenta por meio de execute:

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

O resultado contém seu espaço de trabalho atual. Você também pode buscar com palavras-chave de tarefas como send email. A busca retorna cinco resultados por padrão, aceita um limit de um a 10 e aceita consultas de até 500 caracteres. Se o resultado tiver has_more: true, refine sua consulta para encontrar resultados mais relevantes.

Os resultados da busca não adicionam ferramentas ao catálogo do seu cliente. Nomes mencionados em resultados ou instruções de recuperação também passam por execute. A execução usa suas permissões existentes; se uma operação precisar de mais permissões, seu cliente pode pedir que você as autorize. Encontrar uma ferramenta não concede acesso a ela.

A execução dinâmica retorna dados para ferramentas que normalmente exibem widgets. Use o endpoint padrão para widgets interativos de MCP Apps. Os clientes veem uma única ferramenta de execução, então as configurações de aprovação por ferramenta se aplicam a execute como um todo; verifique a operação selecionada antes de aprovar uma chamada. Este endpoint executa chamadas de ferramentas e não roda JavaScript nem outro código fornecido.

Conecte um cliente

Os exemplos abaixo usam o endpoint padrão. Para descoberta dinâmica, substitua https://mcp.bird.com/dynamic como URL do servidor e siga os mesmos passos de login.

Claude Code

Adicione o servidor:

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

claude mcp list agora mostra bird como ! Needs authentication. O Claude Code não abre o navegador sozinho, então faça login de dentro de uma sessão:

1. Execute /mcp.
2. Selecione bird e pressione Enter.
3. Escolha Authenticate. Seu navegador abre a tela de consentimento do Bird; aprove lá.

O servidor então aparece como conectado e as ferramentas funcionam. Uma execução headless (claude -p) não tem painel /mcp, então autentique-se primeiro pelo shell com claude mcp login bird. Para fazer login novamente depois, /mcp oferece Re-authenticate; Clear authentication remove o token armazenado.

Instalar o plugin bird-ai declara esse servidor para você, substituindo o comando claude mcp add. A autenticação ainda é necessária porque um plugin pode incluir um servidor, mas não pode emitir uma concessão. Selecione /mcp > bird > Authenticate após instalar.

Cursor

Em ~/.cursor/mcp.json:

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

Em seguida, abra Customize na barra lateral do Cursor e selecione MCPs. Encontre bird, siga o prompt de login, aprove a tela de consentimento de Bird no navegador e volte ao Cursor.

OpenCode

O plugin OpenCode de Bird registra o servidor para você, junto com as agent skills de Bird:

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

O OpenCode adiciona todas as ferramentas MCP ao contexto do modelo, então o plugin se conecta ao endpoint dinâmico. Com o modo experimental de código do OpenCode ativado (OPENCODE_EXPERIMENTAL_CODE_MODE=1 ou OPENCODE_EXPERIMENTAL=1), o OpenCode mantém as ferramentas MCP por trás da própria busca, e o plugin se conecta ao catálogo completo em https://mcp.bird.com.

Para adicionar o servidor sem o plugin, coloque isto em opencode.json, no seu projeto ou em ~/.config/opencode/opencode.json:

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

Depois faça login, o que abre o navegador na tela de consentimento de Bird:

opencode mcp auth bird

Reinicie o OpenCode para carregar o plugin. opencode mcp list reporta bird como conectado assim que você aprovar. O plugin, assim como a entrada permission acima, faz o OpenCode perguntar antes de cada chamada execute, porque a ferramenta executada pode alterar seu espaço de trabalho.

VS Code

Em .vscode/mcp.json no seu projeto:

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

Usando settings.json? Coloque a mesma entrada bird em mcp.servers. O VS Code a move para o mcp.json do usuário, que MCP: Open User Configuration abre:

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

O VS Code pede que você confie no servidor na primeira vez que ele inicia, e depois executa o fluxo OAuth por conta própria: aprove a tela de consentimento de Bird na janela do navegador que ele abre. Se nenhuma janela aparecer, inicie ou reinicie bird pelo comando MCP: List Servers e aprove nesse momento. A concessão resultante aparece em Accounts > Manage Trusted MCP Servers, que também é onde você revoga o acesso do VS Code.

ChatGPT e Codex

Instale Bird no ChatGPT ou no Codex, entre no seu espaço de trabalho Bird e peça ao seu agente para enviar mensagens, gerenciar domínios e números e verificar entregas.

Para configurar o Codex manualmente, adicione esta entrada em ~/.codex/config.toml:

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

Depois entre pela sua shell, o que abre o navegador:

codex mcp login bird

Claude

Bird está listado no diretório de conectores do Claude. Abra Bird no diretório e clique em Connect to Claude para fazer o login e aprovar a tela de consentimento. Ative o conector por conversa em + > Connectors. Isso funciona no Claude na web e no aplicativo para desktop.

Para adicioná-lo manualmente, abra Customize > Connectors, clique em + e depois em Add custom connector. Cole https://mcp.bird.com e clique em Add. Em seguida, clique em Connect no conector Bird para fazer o login e aprovar a tela de consentimento. Nos planos Team e Enterprise, um proprietário adiciona o conector uma vez em Organization settings > Connectors, e cada membro ainda clica em Connect em Customize > Connectors para obter sua própria concessão. Ative o conector por conversa em + > Connectors.

Para configurar o ChatGPT manualmente, siga o guia de configuração de app MCP da OpenAI, usando https://mcp.bird.com como URL do servidor e OAuth como autenticação. Conclua o login pelo navegador do Bird e use Bird no seu chat.

Muse

O Muse adiciona Bird como conector personalizado. Em um chat do Muse, peça para configurar um:

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.

O Muse responde com um link de conexão para esta sessão. Abra-o e aprove a tela de consentimento do Bird no navegador. O link funciona apenas para você e expira com a sessão. Se parar de funcionar, peça um novo ao Muse.

Factory Droid

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

Em seguida, execute /mcp dentro do droid e conclua o login pelo navegador a partir do gerenciador de servidores.

Antigravity

O plugin Antigravity de Bird registra o servidor para você, junto com as agent skills de Bird:

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

Para adicionar o servidor sem o plugin, coloque isto em ~/.gemini/config/mcp_config.json, ou em .agents/mcp_config.json para um projeto. O Antigravity lê o endereço de um servidor remoto a partir de serverUrl, então mantenha esse nome de chave:

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

Em seguida, faça login: abra Customizations na barra lateral (no IDE, abra Agent settings com Cmd+, no macOS ou Ctrl+, no Windows e Linux) e selecione Authenticate ao lado de bird. Se bird não aparecer na lista, reinicie o Antigravity. Aprove a tela de consentimento de Bird no navegador, copie o código de autorização exibido, cole-o no Antigravity e selecione Submit.

Agent Plugins

O plugin bird-ai declara este servidor em um mcp.json que segue o padrão Agent Plugins. Um host que implementa a especificação lê esse arquivo quando o plugin é instalado, então não há configuração de servidor para escrever: instale o plugin e faça login.

Qualquer outro host

Procure a configuração que adiciona um servidor MCP remoto, HTTP ou personalizado, geralmente em um menu Connectors ou Integrations, e informe a URL. A localização do campo varia; use a URL do endpoint hospedado que você escolheu. Em seguida, encontre o mecanismo de login desse cliente: um controle Connect, Authorize ou Needs login ao lado do servidor, um subcomando login, ou uma janela do navegador que o cliente abre sozinho. Um cliente que lista as ferramentas de Bird mas falha em todas as chamadas tem a URL, mas ainda precisa de uma concessão.

O que acontece quando você faz login

Seu navegador abre uma tela de consentimento do Bird. Faça login, escolha se deseja conceder permissões do espaço de trabalho ou da organização e selecione quais permissões delegar. Como clientes MCP se registram sozinhos, o nome do cliente é autodeclarado, então a tela o sinaliza como not verified by Bird. Confirme que é o cliente que você realmente iniciou antes de aprovar. Depois disso, as ferramentas aparecem na lista do agente e o token é renovado silenciosamente, então este é um passo único por cliente.

A maneira mais rápida de provar que funcionou é pedir ao agente para chamar whoami: ele retorna o usuário autenticado, então uma resposta real significa que a concessão está ativa. No endpoint dinâmico, chame-o por meio de execute com tool: "whoami" e arguments vazio.

A concessão é limitada à interseção do que o cliente solicitou, do que você aprovou e do que você realmente possui; escopos org:owner e platform-admin nunca são delegáveis. Ela aparece na lista Connected apps do seu perfil, e revogá-la ali desconecta o cliente imediatamente.

Como o handshake funciona

Você não precisa disso para conectar um cliente. Isso importa se você está depurando um cliente que não consegue autenticar, ou escrevendo um.

O servidor hospedado fala Streamable HTTP e não exige credenciais: ele não armazena segredos e não valida nada por conta própria. Cada requisição carrega o seu próprio token bearer OAuth, que o API da Bird valida a cada requisição. O servidor é stateless e o tráfego regional é roteado automaticamente, então a única URL funciona de qualquer lugar.

O fluxo de login usa MCP padrão. Os clientes diferem apenas no que o aciona: a primeira chamada de ferramenta ou a seleção de Authenticate. Depois que o fluxo começa, as etapas de autenticação não precisam de configuração extra:

1. O cliente faz uma requisição não autenticada e recebe 401 com um header WWW-Authenticate apontando para os metadados de recurso protegido (RFC 9728) da Bird (/.well-known/oauth-protected-resource).
2. A partir daí, ele descobre o servidor de autorização e então se registra dinamicamente (RFC 7591). O registro dinâmico elimina a necessidade de um client ID pré-compartilhado ou configuração manual.
3. Seu navegador abre a tela de consentimento da Bird.
4. O cliente troca o resultado por um token de acesso (PKCE; renovado automaticamente) e as ferramentas Bird aparecem.

Local: execute via stdio com o CLI

Execute o servidor MCP local dentro do bird CLI para agentes com acesso ao shell ou acesso a arquivos na sua máquina. Instale o CLI, execute bird auth login uma vez e aponte seu cliente para o comando bird mcp.

Você não executa bird mcp diretamente: seu cliente o inicia e se comunica com ele via stdin/stdout. Todo cliente precisa dos mesmos dois dados: o comando (bird) e o argumento (mcp). Esse caminho não exige login por cliente porque bird auth login já possui a concessão.

Cursor

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

VS Code

Em .vscode/mcp.json no seu projeto:

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

Claude Code

claude mcp add bird -- bird mcp

Como o servidor local se autentica

O servidor local age como você e reutiliza o login armazenado do CLI. bird auth login abre um fluxo OAuth no navegador onde você concede um subconjunto das permissões do seu espaço de trabalho. O token emitido tem os mesmos limites de permissão da concessão hospedada. Nem org:owner nem escopos platform-admin estão disponíveis. bird mcp lê e renova o login armazenado a partir do arquivo de credenciais CLI, cujo modo é 0600. Assim como no servidor hospedado, a configuração do seu cliente não contém BIRD_API_KEY nem nenhum outro segredo. Se o login estiver ausente, bird mcp se recusa a iniciar e pede que você execute bird auth login.

Você não expõe um listener: o servidor roda na sua máquina, dentro do sandbox do cliente, apenas pelo tempo que o cliente precisar. O host API segue a região do seu login automaticamente; --base-url (ou BIRD_API_URL) substitui essa região para testes em um ambiente que não é de produção.

O que as ferramentas cobrem

O conjunto de ferramentas abrange todos os canais que a Bird opera, além das tarefas de conta e configuração relacionadas. Ele é curado, e não a superfície completa da API: cada ferramenta é direcionada a uma tarefa que um agente realmente executa, e operações destrutivas são anotadas para que os hosts possam perguntar antes de executá-las.

E-mail tem o maior número de ferramentas, porque tem a maior superfície para configurar. Os outros canais seguem a mesma estrutura de envio e leitura.

Mensagens

• Enviar e inspecionar e-mail: email_send, email_send_batch, email_list e email_get, que retorna a mensagem com o status agregado de entrega. Status de entrega por destinatário e o log de eventos são chamadas de ferramenta separadas.
• Enviar e inspecionar SMS: sms_send, sms_send_batch, sms_get, sms_list e sms_list_events, espelhando a estrutura do e-mail. sms_templates_list e sms_templates_get leem o catálogo de templates.
• Enviar e inspecionar WhatsApp: whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events e whatsapp_media. Templates são uma superfície completa de autoria sob whatsapp_templates_*, incluindo conteúdo por versão e por idioma.
• Inspecionar trechos de chamadas de voz: voice_legs_get e voice_legs_list leem trechos de chamadas, com estatísticas por país e por código de resposta em voice_stats_*. voice_session_credentials_create cria a credencial do espaço de trabalho que um cliente SIP ou softphone usa para se autenticar.
• Verificar um destinatário: verify_verifications_create envia um código de verificação de uso único, verify_verifications_check valida o que o destinatário enviou e verify_verifications_next_channel recorre a outro canal.
• Criar uma chamada de voz (preview): voice_calls_create prepara uma chamada de saída usando a publicação ativa de uma sequência habilitada e não arquivada. Uma pessoa revisa e executa a solicitação no navegador; preparar a chamada não a realiza. Consulte Criar uma chamada de voz para permissões e instruções de como tentar novamente. O servidor local bird mcp requer uma versão de CLI que inclua essa ferramenta.

Preparando um canal para enviar

• Configurar domínios de envio: email_domains_create adiciona um domínio de envio e retorna os registros DNS a publicar; email_domains_verify os reverifica; além de email_domains_list e email_domains_get.
• Reivindicar e registrar remetentes SMS: sms_senders_create reivindica um remetente, sms_senders_requirements informa o que um país exige dele e sms_senders_registrations_create o registra. O tráfego A2P nos EUA passa pelas ferramentas de marca, campanha e submissão de sms_10dlc_*.
• Provisionar números: numbers_available_list pesquisa, numbers_orders_create compra, numbers_cancel devolve ao final do período pago (ou imediatamente quando o número não tem assinatura) e numbers_release devolve agora. whatsapp_numbers_precheck informa se WhatsApp aceitará um número antes de você solicitá-lo.
• Verificar se a conta consegue enviar: as ferramentas trust_* informam os requisitos da organização que condicionam a compra de um número ou o registro de um remetente.

Entregabilidade de e-mail

• Criar templates de e-mail: email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate e email_templates_preview (renderiza um rascunho com valores de exemplo sem enviar). As versões ficam em email_templates_versions_*, onde email_templates_versions_submit congela um rascunho e o torna a versão servida pelos envios, e email_templates_versions_languages_* edita o conteúdo por idioma de um rascunho. Nada que um agente escreva chega a um destinatário até ser submetido.
• Gerenciar supressões: email_suppressions_list, email_suppressions_check (é seguro enviar para este endereço?), email_suppressions_add e email_suppressions_remove (anotada como destrutiva, porque remover uma supressão sem motivo prejudica a reputação do remetente).
• Gerenciar IPs dedicados e pools: email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (mover um para um pool) e email_dedicated_ips_delete; além de email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update e email_ip_pools_delete para os pools pelos quais você roteia seus envios.

Audiência e configuração

• Gerenciar contatos e audiências: contacts_* e contact_properties_* para as pessoas para quem você envia, audiences_* para as listas para as quais você envia e preferences_* para concessões de consentimento e opt-outs.
• Provisionar Realtime: realtime_apps_* e realtime_apps_keys_* criam os apps e as chaves com que os clientes Realtime se conectam.
• Consultar alguém: lookup_phone_number e lookup_email informam o que Bird sabe sobre um endereço antes de você enviar para ele.
• Inspecionar configuração: webhooks_list, workspace_get e whoami (o usuário autenticado: id, email, nome).

Seu cliente exibe a lista de ferramentas ativas com nomes, descrições e schemas de entrada. Trate essa listagem como o inventário oficial. Uma boa primeira tarefa para testar de ponta a ponta:

Call whoami to find my email, then send me a test email from onboarding@messagebird.dev and tell me when it's delivered.

MCP ou a CLI?

Mesma superfície, mesmo modelo de autenticação, chamadores diferentes. Para agentes com acesso a shell (Claude Code, terminal do Cursor, CI), a CLI é mais enxuta: saída JSON, códigos de saída semânticos e muito menos tokens por operação. MCP é para hosts que chamam ferramentas em vez de executar shells, e o endpoint hospedado alcança os que não conseguem executar um binário (Claude Desktop, ChatGPT, mobile). Você não precisa decidir agora: a URL hospedada não exige instalação, e a bird mcp local já está disponível assim que a CLI estiver.

Próximos passos

• MCP Events: inscreva seu cliente em eventos Bird, como novo e-mail em uma caixa de entrada, e receba cada um como um webhook assinado.
• Consultar analytics de e-mail com IA: pergunte sobre entrega, engajamento e latência em linguagem natural.
• Onboarding com IA: a versão quickstart desta página, mais o corpus de documentação legível por máquina.
• Agent skills: o plugin bird-ai do marketplace, skills mais este servidor MCP, instalados em um único passo.
• CLI para agentes: controle o Bird a partir de agentes com acesso ao shell sem MCP: saída JSON, códigos de saída semânticos, login via OAuth.
• Autenticação: chaves API, regiões e como as requisições são autorizadas.