Pidgeon

npx add-mcp 'https://pidgeon.ai/api/mcp'

Um agente pode gerenciar diretamente uma caixa de entrada do Pidgeon: lê-la, responder a partir dela, criar endereços nela. O Pidgeon usa o Model Context Protocol pela mesma API descrita nesta documentação — um adaptador de protocolo, e nada mais.

Há duas formas de acessar, e ambas usam o mesmo servidor. A versão hospedada não precisa de instalação; o pacote executa o servidor na sua máquina.

Hospedado, ou seja, uma URL

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp

A primeira chamada responde 401, e o cliente direciona você ao Pidgeon para entrar. Você escolhe o que ele pode fazer — ler, ler e enviar ou acesso total — e a que pode ter acesso: um endereço ou todos os endereços, se você for o proprietário da conta. Essa escolha se torna uma chave de API, e o cliente guarda um token para ela. Ela aparece em Developers → API keys → Connected apps, e desconectá-la ali encerra o acesso na próxima chamada do cliente.

Claude's custom connectors, ChatGPT, Grok, Cursor, Codex e VS Code usam a mesma URL e fazem login da mesma forma. Cada solicitação é respondida por conta própria: o servidor não mantém uma sessão, pois não tem estado próprio para guardar.

Para um agente sem ninguém disponível para fazer login, envie uma chave:

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp \
--header "Authorization: Bearer $PIDGEON_API_KEY"

x-api-key também funciona. Instruções passo a passo para Cursor, Codex (que lê TOML, não JSON) e VS Code; Windsurf e Gemini CLI usam a mesma URL e o mesmo cabeçalho.

No Grok

No Grok, acesse Connectors → Custom, cole https://pidgeon.ai/api/mcp e faça login na tela de consentimento; não é necessária uma chave (instruções passo a passo). O Muse da Meta está em análise pela Meta.

No Cursor

Adicione o Pidgeon ao Cursor pela listagem dele no cursor.directory, que inclui o servidor hospedado e a skill.

Ou adicione o servidor manualmente, em ~/.cursor/mcp.json (ou .cursor/mcp.json para um projeto). A URL é tudo de que ele precisa; o Cursor faz seu login na primeira chamada:

{
"mcpServers": {
  "pidgeon": {
    "url": "https://pidgeon.ai/api/mcp"
  }
}
}

Para um agente sem ninguém disponível para fazer login, adicione "headers": { "Authorization": "Bearer ${env:PIDGEON_API_KEY}" } ao lado da URL, e o Cursor o preencherá a partir do seu ambiente.

Codex, VS Code e Gemini CLI

Para Codex, VS Code e Gemini CLI, um comando grava o servidor no próprio arquivo do cliente:

npx -y @pidgeon-ai/mcp init --client codex    # ~/.codex/config.toml
npx -y @pidgeon-ai/mcp init --client vscode   # .vscode/mcp.json
npx -y @pidgeon-ai/mcp init --client gemini   # .gemini/settings.json

Sem uma chave definida, ele grava apenas a URL, e o cliente faz seu login. Com PIDGEON_API_KEY definido, ele verifica primeiro a chave e, em seguida, faz o cliente lê-la dessa variável (Codex, Gemini CLI) ou solicitá-la uma vez (VS Code), para que a chave nunca seja gravada no arquivo. Ele acrescenta conteúdo ao que já existe, inclusive comentários, faz uma cópia do arquivo que altera em <file>.bak, não faz nada na segunda execução e só substitui uma entrada pidgeon diferente com --force. --scope user ou --scope project seleciona o outro arquivo; --print não grava nada.

Ou instalado, ou seja, um pacote

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp init

Isso verifica a chave na API antes de gravar qualquer coisa e informa a quais endereços ela dá acesso — a única pergunta que um bloco de JSON não pode responder e que, de outro modo, só aparece quando um modelo recebe silenciosamente um erro que você nunca vê. Em seguida, grava .mcp.json no diretório atual e mostra o que gravou. Nunca substitui uma entrada que já esteja lá: --force faz isso, e --print mostra a configuração sem gravar nada, o que é útil se o seu cliente mantiver a própria configuração em outro lugar.

A chave é referenciada a partir do ambiente, em vez de ser gravada no arquivo, para que a configuração possa ser enviada ao repositório sem expor a credencial:

{
"mcpServers": {
  "pidgeon": {
    "command": "npx",
    "args": ["-y", "@pidgeon-ai/mcp"],
    "env": { "PIDGEON_API_KEY": "${PIDGEON_API_KEY}" }
  }
}
}

Claude Desktop ou qualquer outro cliente MCP usa o mesmo bloco. Para executar o servidor diretamente, o que é mais útil para acompanhar a inicialização:

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp

PIDGEON_BASE_URL aponta para outro ambiente que não o de produção, o que só é útil se você estiver executando o Pidgeon por conta própria.

A chave é todo o controle de acesso

Isso entrega uma chave de API a um modelo — uma que você criou ou que concedeu ao fazer login. Nada no pacote decide a que se pode ter acesso: o limite da própria chave e os endereços aos quais ela foi concedida fazem todo o controle, no servidor, exatamente como para qualquer outro chamador. Não há um segundo conjunto de regras que possa dar errado.

Portanto, forneça a chave mais restrita de que o agente precisa. Uma chave criada em read nunca poderá enviar, por mais permissões que tenha para uma caixa de entrada — consulte Autenticação para entender o alcance de uma chave e como restringi-lo. Um agente que só faz triagem deve ter uma chave que só permita leitura; assim, a possibilidade de ele enviar algo constrangedor deixa de depender do prompt.

O alcance de uma chave é uma fotografia dos endereços aos quais ela foi concedida; portanto, um endereço criado depois da chave não estará incluído nela.

O que ele expõe

Todos os 42, lidos da própria lista do servidor para que esta página não fique desatualizada:

Ferramenta	Função	Endpoint
list_addresses	Os endereços aos quais esta credencial pode ter acesso.	GET /identities
create_address	Cria um endereço para um agente usar.	POST /identities
get_address	Um endereço, pelo id.	GET /identities/{id}
list_threads	Conversas em um endereço, da mais recente para a mais antiga.	GET /threads
get_thread	Uma conversa, pelo id.	GET /threads/{id}
list_messages	As mensagens de uma conversa, da mais antiga para a mais recente — o texto a ler antes de responder.	GET /messages
search_messages	Pesquisa de texto completo em todos os endereços aos quais esta credencial pode ter acesso, ordenada por relevância.	GET /messages/search
send_message	Envia a partir de um endereço que esta credencial tem permissão para usar como remetente.	POST /messages
get_message	Uma mensagem, pelo id, com o corpo, os cabeçalhos que mantemos e o que os registros do domínio remetente comprovaram — authentication.spf\, .dkim\, .dmarc\, em que null significa que não foi informado, e não que falhou.	GET /messages/{id}
await_message	Aguarda até que uma mensagem chegue a um endereço — por exemplo, depois que você envia um formulário de cadastro — e a retorna com extracted.codes\ e extracted.links\: códigos de verificação e links de confirmação, provavelmente primeiro.	GET /messages/await
reply_to_message	Os destinatários, o assunto e a conversa são extraídos da mensagem respondida; você fornece apenas o texto.	POST /messages/{id}/reply
forward_message	Encaminha uma mensagem a alguém a quem ela não foi endereçada, com seus anexos, a partir do endereço que a recebeu.	POST /messages/{id}/forward
create_draft	Escreve uma mensagem sem enviá-la, para que uma pessoa a leia e envie — use quando pedirem que você prepare respostas para aprovação.	POST /drafts
get_draft_approval	Informa o estado de um envio retido, pelo seu draft\_id\: pending\ até que uma pessoa o aprove ou rejeite no painel; depois, approved\ (foi enviado, e message\_id\ é a mensagem), rejected\ ou expired\ após 24 horas sem que ninguém decida.	GET /drafts/{id}/approval
list_drafts	Todos os rascunhos de um endereço, do mais recente para o mais antigo, com destinatários e corpo — para que você possa voltar a um deles e terminá-lo.	GET /drafts
get_draft	Um rascunho pelo id: remetente, destinatários, assunto, texto e anexos.	GET /drafts/{id}
update_draft	Altera os campos informados e mantém os demais; null\ limpa o assunto ou o texto.	PATCH /drafts/{id}
delete_draft	Exclui um rascunho e cancela seu envio, caso esteja agendado.	DELETE /drafts/{id}
read_attachment	O texto de um anexo — um CSV, log, JSON, arquivo de calendário ou PDF, documento do Word .docx\ ou planilha do Excel .xlsx\.	GET /attachments/{id}/text
update_thread	Quem é responsável por uma conversa e em que etapa ela está.	PATCH /threads/{id}
update_message	Marca uma mensagem com estrela ou a move para archive\, spam\ ou trash\.	PATCH /messages/{id}
list_send_rules	A lista de permissões e bloqueios de um endereço e a política de envio associada a ela.	GET /identities/{id}/send-rules
list_receive_rules	As regras que determinam o que chega a um endereço — rejeitar, marcar como spam, mover para a lixeira, arquivar ou enviar para a caixa de entrada, por remetente ou domínio — e seu receive\_policy\.	GET /identities/{id}/receive-rules
list_folders	Todas as pastas de um endereço e suas contagens.	GET /mailboxes
list_folder	Uma pasta de um endereço, da mais recente para a mais antiga, com uma conversa por linha — enquanto list\_threads\ informa quais conversas existem, esta mostra onde estão arquivadas e como aparecem em uma lista.	GET /mailboxes/{folder}
list_changes	Tudo o que mudou em uma caixa de entrada desde um sync\_cursor\, inclusive mensagens recebidas, para que um agente de longa duração não precise reler uma pasta para encontrar uma nova mensagem.	GET /mailboxes/changes
list_events	Todos os eventos de todos os endereços aos quais esta credencial pode ter acesso — mensagens recebidas, enviadas, entregues, devolvidas e arquivadas.	GET /events
list_labels	Os marcadores pertencem a um endereço, não ao espaço de trabalho; portanto, o mesmo nome em três endereços corresponde a três marcadores com três ids.	GET /labels
create_label	Um marcador de um endereço.	POST /labels
apply_label	O marcador precisa pertencer ao mesmo endereço da conversa — list\_labels\ desse endereço fornece o id correto.	POST /threads/{id}/labels
remove_label	Remove um marcador de uma conversa.	DELETE /threads/{id}/labels
list_pods	Um pod é um contêiner para um cliente seu: ele contém endereços e domínios, e **as mensagens enviadas a partir dele usam a própria reputação de envio**, para que um cliente não prejudique a entrega de mensagens de outro.	GET /pods
create_pod	Um contêiner para um cliente seu, com reputação de envio própria.	POST /pods
get_metrics	Mensagens enviadas, entregues, devolvidas, rejeitadas, denunciadas, recebidas e marcadas como spam em um período de days\ — contadas a partir do registro de eventos, incluindo resultados informados posteriormente pelo provedor.	GET /metrics
get_calendar	O calendário de um endereço, pelo id\ do endereço: seu fuso horário padrão e a quantidade de eventos que contém.	GET /identities/{id}/calendar
update_calendar	O fuso horário atribuído a um evento criado sem um, como um nome IANA do tipo Europe/Lisbon\.	PATCH /identities/{id}/calendar
get_agenda	O que consta no calendário de um endereço entre after\ e before\ (data e hora ISO 8601), em ordem de início, com cada ocorrência de um evento recorrente listada separadamente.	GET /identities/{id}/calendar/agenda
get_calendar_event	Um evento pelo eventId\ no calendário do endereço id\: horários, descrição, local, recorrência e participantes com suas respostas.	GET /identities/{id}/calendar/events/{eventId}
create_calendar_event	Adiciona um evento ao calendário do endereço id\.	POST /identities/{id}/calendar/events
update_calendar_event	Altera um evento do calendário: modifica os campos informados e mantém os demais.	PATCH /identities/{id}/calendar/events/{eventId}
delete_calendar_event	Remove um evento do calendário do endereço id\.	DELETE /identities/{id}/calendar/events/{eventId}
respond_to_invitation	Responde a um convite de reunião recebido por e-mail, usando o id\ da mensagem: accepted\, declined\ ou tentative\, com um comment\ opcional.	POST /messages/{id}/invitation/respond

Cada ferramenta corresponde ao endpoint ao lado na referência, com as mesmas recusas. Uma ferramenta proibida para a chave falha da mesma forma que a API, com a mensagem que a API teria usado.

A pesquisa abrange todos os endereços aos quais a chave pode ter acesso, a menos que você especifique um; cada resultado informa em qual endereço foi encontrado.

O que ele não é

Ele não é um ambiente de execução de agentes e não toma decisões. O Pidgeon não tem opinião sobre qual modelo você executa nem sobre o que ele pode concluir — a mesma posição adotada em Threads and hand-off para o restante do produto. Se o agente ficar sem saber como prosseguir, encaminhar a conversa a uma pessoa é um status da conversa, não um recurso deste pacote.