Register Agent Inbox as an MCP server and skill for Claude Code, Codex, or Cursor, and verify a GitHub sign-up end to end.
agent-inbox init --agent claude --skillYour agent can already call the agent-inbox CLI. agent-inbox init goes one step further: it registers an MCP server so the mailbox shows up as tools, and it can write a skill that tells the agent when and how to use it.
Install the CLI first. Then run init in the project folder.
init never writes a token into any config file. agent-inbox mcp reads the token from ~/.agent-inbox/mailboxes when it starts. Restart your agent after running init.
agent-inbox init --agent claude --skill
This adds an agent-inbox server to .mcp.json and writes .claude/skills/agent-inbox/SKILL.md. An existing different agent-inbox entry is not replaced unless you pass --force.
To wake an idle Claude Code session when mail arrives, add a channel:
agent-inbox init --agent claude --skill --channel
claude --dangerously-load-development-channels server:agent-inbox-channel
--channel adds an agent-inbox-channel server to .mcp.json. Each new e-mail is pushed into the running session. Channels are a Claude Code research preview, which is why the launch flag is needed.
agent-inbox init --agent codex
This appends an [mcp_servers.agent-inbox] table to ~/.codex/config.toml (or $CODEX_HOME/config.toml). It runs agent-inbox mcp. Nothing is changed if the table already exists.
agent-inbox init --agent cursor
This adds the same server to .cursor/mcp.json.
To set up all three at once, use --agent all.
The MCP server exposes the mailbox's read tools plus two helpers:
| Tool | Purpose |
|---|---|
inbox_whoami | Returns the mailbox: its address, label, expiry and sender allow-list — so the agent knows what to type into a form. |
inbox_wait_for_email | Blocks until a new e-mail arrives, up to 120 seconds (timeoutSeconds). Pass sinceId to ignore older mail. |
The tools are read-only. There is no send tool.
The MCP server needs a mailbox to exist. Create one first with agent-inbox new, or tell the agent to run it.
You ask your agent: "Create a GitHub account for this test project."
The agent gets an address, limited to GitHub:
agent-inbox new --label "github signup" --allow "*@github.com"
On the hosted service this answers at once, with no login. It prints something like brisk-otter-7k3fq2@agent.funai.io. If the server needs a human, it prints a code and a link. Open the link and approve it.
The agent fills in the GitHub sign-up form with that address.
GitHub sends a verification code. The agent waits for it:
agent-inbox wait --from github --timeout 5m
The message is printed between <<<EXTERNAL EMAIL ...>>> markers. The agent reads the code from the body and types it into the form.
The agent gives the address up:
agent-inbox rm
If wait exits with code 2, nothing arrived in time. Check that the sender is on the allow-list. If GitHub mail is refused, add it with agent-inbox allow add "*@github.com", or ask the human to.
The agent should use the code once and never paste it into commits, logs, issues, or chat.
agent-inbox skill prints the skill text, so you can paste it into any agent that reads instructions from a file.
See also: CLI reference.