Agentboxd

@agentboxd/mcp

MCP server for Agentboxd: real email inboxes for AI agents.

Add it to Claude Desktop, Claude Code, Cursor or any MCP client, and the model can create an email address, send and reply, wait for the next email, and pull verification codes and magic links out of sign-up and login emails. All it needs is an API key.

npx -y @agentboxd/mcp        # stdio; needs AGENTBOXD_API_KEY in the environment

Get a key from the dashboard (the Free plan needs no card). Keys start with mr_.

No install needed? The same tools (minus signup) are hosted at https://mcp.agentboxd.com/mcp: add that URL as a custom connector in Claude, or run claude mcp add --transport http agentboxd https://mcp.agentboxd.com/mcp, and sign in to Agentboxd when asked. See the docs.

Setup

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart Claude Desktop:

{

"mcpServers": { "agentboxd": { "command": "npx", "args": ["-y", "@agentboxd/mcp"], "env": { "AGENTBOXD_API_KEY": "mr_..." } } } }

Claude Code

claude mcp add agentboxd -e AGENTBOXD_API_KEY=mr_... -- npx -y @agentboxd/mcp

Add --scope user to make it available in every project.

Cursor

.cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects:

{

"mcpServers": { "agentboxd": { "command": "npx", "args": ["-y", "@agentboxd/mcp"], "env": { "AGENTBOXD_API_KEY": "mr_..." } } } }

VS Code, Windsurf, Cline and other stdio clients

Same shape everywhere: command npx, args ["-y", "@agentboxd/mcp"], env AGENTBOXD_API_KEY. Or install globally and run the binary directly:

npm install -g @agentboxd/mcp

AGENTBOXD_API_KEY=mr_... agentboxd-mcp

Streamable HTTP

AGENTBOXD_API_KEY=mr_... npx -y @agentboxd/mcp --http            # http://127.0.0.1:3333/mcp

AGENTBOXD_API_KEY=mr_... npx -y @agentboxd/mcp --http --port=4000

HTTP mode is stateless and has no authentication of its own: anyone who can reach the port acts with your key. It binds to 127.0.0.1 by default; don't expose it without a reverse proxy that adds auth.

Configuration

No API key yet: the agent signs itself up

Start the server without AGENTBOXD_API_KEY and the agent gets a signup tool. It solves a short proof-of-work challenge (a few seconds of CPU), creates an unclaimed workspace with one inbox, and the server uses the new key for the rest of the session. Nothing is written to disk by default: the tool returns the key once and tells the agent to hand it to you. Pass --save-key= if the server should keep it across restarts.

Until a person claims the workspace (the agent passes owner_email to signup, or calls request_claim later), it is limited: one inbox, email to at most 20 new recipients a day (replies in threads someone started with the agent are not limited), no webhooks or custom domains. Idle unclaimed workspaces are deleted after 30 days. get_account shows the status and limits. Details: https://agentboxd.com/docs/agent-signup

Tools

Messages come back as compact JSON: id, thread_id, direction, from, to, subject, received_at/sent_at, extracted_text (the new content, with quoted history and signatures removed, cut at 8,000 characters with a note), ai.verification, attachment metadata and labels. Raw HTML is left out unless you pass include_html: true. API errors come back as tool errors (isError) with the API's { error: { code, message } }, so the server keeps running.

Tip for `since`: the wait tools only count mail that arrives after the call starts. If the email may already have arrived, record the time before you tri