MCP

An agent can hold a Pidgeon inbox directly: read it, answer from it, create addresses in it. Pidgeon speaks Model Context Protocol over the same API this documentation describes — a protocol adapter, and nothing more.

There are two ways in and they are the same server. The hosted one needs no install; the package runs it on your machine.

Hosted, which is a URL

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

The first call answers 401, and the client sends you to Pidgeon to sign in. You choose what it can do — read, read and send, or full access — and what it can reach: one address, or every address if you own the account. That choice becomes an API key, and the client holds a token for it. It shows up under Connected apps, and Disconnect there ends it on the client's next call.

Claude's custom connectors, ChatGPT, Grok, Cursor, Codex and VS Code take the same URL and sign in the same way. Each request is answered on its own: the server holds no session, because it has no state of its own to keep.

For an agent with nobody there to sign in, send a key instead:

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

x-api-key works too. Cursor, Codex (which reads TOML, not JSON), VS Code, Windsurf and Gemini CLI take the same URL and header; the integrations list has each one.

In Grok

In Grok, Connectors → Custom, paste https://pidgeon.ai/api/mcp, and sign in at the consent screen; no key is needed. Meta's Muse is in review with Meta.

In Cursor

Add Pidgeon to Cursor from its cursor.directory listing, which carries the hosted server and the skill.

Or add the server by hand, in ~/.cursor/mcp.json (or .cursor/mcp.json for one project). The URL is all it needs; Cursor signs you in on the first call:

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

For an agent with nobody there to sign in, add "headers": { "Authorization": "Bearer ${env:PIDGEON_API_KEY}" } beside the URL, and Cursor fills it from your environment.

Codex, VS Code and Gemini CLI

For Codex, VS Code and Gemini CLI, one command writes the server into the client's own file:

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

With no key set it writes the URL alone, and the client signs you in. With PIDGEON_API_KEY set it checks the key first, then has the client read it from that variable (Codex, Gemini CLI) or ask for it once (VS Code), so the key never lands in the file. It adds to what is there, comments included, copies a file it changes to <file>.bak, does nothing the second time, and replaces a different pidgeon entry only with --force. --scope user or --scope project picks the other file; --print writes nothing.

Or installed, which is a package

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

That checks the key against the API before it writes anything, and tells you which addresses it reaches — the one question a block of JSON cannot answer, and the one that otherwise surfaces as a model quietly getting an error you never see. Then it writes .mcp.json in the current directory and prints what it wrote. It never replaces an entry that is already there: --force does that, and --print shows the config without writing anything, which is what you want if your client keeps its own somewhere else.

The key is referenced from the environment rather than written into the file, so the config can be committed and the credential cannot:

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

Claude Desktop, or any other MCP client, takes the same block. To run the server directly, which is mostly useful for watching it start:

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

PIDGEON_BASE_URL points it somewhere other than production, which is only useful if you are running Pidgeon yourself.

The key is the whole of the access control

This hands an API key to a model — one you minted, or one you granted by signing in. Nothing in the package decides what may be reached: the key's own ceiling and the addresses it was granted do all of it, server-side, exactly as for any other caller. There is no second set of rules here to get wrong.

So give it the narrowest key the agent needs. A key created at read can never send, however generously it is granted an inbox — see Authentication for what a key's reach means and how to narrow it. An agent that only triages should hold a key that only reads, and then the question of whether it might send something embarrassing is not a question about the prompt.

A key's reach is a snapshot of the addresses it was granted, so an address created after the key is not in it.

What it exposes

All 61 of them, read from the server's own list so this page cannot be behind it:

Each is the endpoint beside it in the reference, with the same refusals. A tool that is forbidden to the key fails the way the API fails, with the sentence the API would have used.

Search covers every address the key reaches unless you name one, and each result says which address it was found in.

Send later

To send at a time, pass send_at to send_message or reply_to_message (ISO 8601 with an offset, such as 2026-11-04T09:00:00+01:00, a minute to 90 days ahead), or schedule_draft for a draft already written. Pidgeon sends it then, from its side, even if you and your agent are offline, so prefer it to a task your agent schedules for itself. The answer is status: scheduled with a cancel call, and unschedule_draft takes it back. Each scheduled message goes on its own: one refused never stops the rest. On an address that asks a person first, it waits for their approval and goes at its time once they give it.

What it is not

It is not an agent runtime, and it does not decide anything. Pidgeon has no opinion about which model you run or what it is allowed to conclude — the same position Threads and hand-off takes about the rest of the product. If the agent gets stuck, handing the conversation to a person is a thread status, not a feature of this package.

Further reading: email MCP servers for sending and receiving, compared.