Agentboxd MCP Server

Agentboxd

Real email inboxes for AI agents. Create an address with one API call, send and reply from it, block until the next email arrives, and pull the one-time code or magic link out of a sign-up email.

This repository holds the open-source clients for the hosted Agentboxd API:

What you get

• Real addresses on homingbox.net or your own domain, with SPF, DKIM and DMARC handled.
• Mail as clean JSON: extracted_text holds only the new text of a reply, without quoted history or signatures; attachments, threads and authentication results are all there.
• Wait instead of poll: messages.wait() long-polls until the next matching email arrives.
• Verification codes and magic links extracted from sign-up and login emails, with a confidence score.
• Temporary inboxes that delete themselves (and their mail) after a TTL you choose.
• Signed webhooks for message.received and friends, plus a verifier in each SDK.
• Untrusted-input handling: messages that fail SPF/DMARC or look like prompt injection are labelled, and the MCP server marks every result that contains email content.

60-second quickstart

Get an API key from the dashboard (Free plan, no card), then:

export AGENTBOXD_API_KEY=mr_...

TypeScript

import { Agentboxd } from 'agentboxd';

const mr = new Agentboxd(); // reads AGENTBOXD_API_KEY
const inbox = await mr.inboxes.create({ client_id: 'my-agent' }); // idempotent on client_id
console.log(inbox.address);

const since = new Date().toISOString();
// ...sign up somewhere with inbox.address...
const v = await mr.messages.waitForVerification(inbox.id, { since, timeout: 60 });
console.log(v?.code ?? v?.link);

Python

from agentboxd import Agentboxd

with Agentboxd() as mr:  # reads AGENTBOXD_API_KEY
    inbox = mr.inboxes.create(client_id="my-agent")
    msg = mr.messages.wait(inbox["id"], timeout=60)
    if msg:
        mr.messages.reply(inbox["id"], msg["id"], text="Got it, thanks!")

MCP (Claude Code)

The hosted connector needs no API key: you sign in and choose what the client may do.

claude mcp add --transport http agentboxd https://mcp.agentboxd.com/mcp

Or run the server locally with a key:

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

Then ask: "Create an inbox, sign up for the newsletter at example.com with it, and tell me the confirmation link." Config snippets for Claude Desktop, Cursor and other clients are in mcp/README.md.

Docs

• Quickstart · API reference
• Verification codes · Webhooks · Temporary inboxes · Custom domains
• MCP server · TypeScript SDK · Python SDK
• Machine-readable: llms.txt

Examples

• examples/echo-agent.ts: registers a webhook and replies to every email with a short summary. Needs a public URL for the webhook (e.g. a tunnel): AGENTBOXD_API_KEY=mr_... AGENTBOXD_BASE_URL=https://api.agentboxd.com ECHO_WEBHOOK_URL=https://<your-tunnel>/webhook npm run echo-agent
• examples/deepseek-agent/: a tool-calling agent that signs up for things and triages an inbox, with the email-is-untrusted guardrails wired in.

npm install          # dev tooling for the examples (tsx, vitest)
npm run echo-agent
npm run deepseek-agent -- --demo signup

Repository layout

sdk/          TypeScript client (npm: agentboxd), zero runtime dependencies
mcp/          MCP server (npm: @agentboxd/mcp); inlines the TypeScript client at build time
sdk-python/   Python client (PyPI: agentboxd, coming soon)
examples/     Example agents using the TypeScript client

The Agentboxd API server itself is not part of this repository.

Contributing and security

Issues and pull requests are welcome: see CONTRIBUTING.md. Please report security problems privately as described in SECURITY.md, not in public issues.

License

MIT