MCP, for agents

A mailbox an agent can hold, over the Model Context Protocol.

An agent can hold a Pidgeon mailbox directly: read it, answer from it, create addresses in it. @pidgeon-ai/mcp is a Model Context Protocol server over the same API this documentation describes — a protocol adapter, and nothing more.

Running it

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

Claude Desktop, or any other MCP client:

json

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

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. 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 a mailbox — 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

Tool	Does
`list_addresses`	Every address the key reaches
`get_address`	One address, with its capabilities
`create_address`	A new programmable address
`list_threads`	Conversations in a mailbox
`get_thread`	One conversation, with its messages
`list_messages`	Messages in a mailbox, newest first
`search_messages`	Full-text across what the key reaches
`send_message`	Send, or reply in a thread
`list_send_rules`	What an address is permitted to send, and to whom

Each is the endpoint of the same name 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.

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.

Search the docs

Running it

The key is the whole of the access control

What it exposes

What it is not