# mailbox.bot MCP server Official hosted Model Context Protocol server for **[mailbox.bot](https://mailbox.bot)**. Production is remote Streamable HTTP at `https://mailbox.bot/api/mcp`. Agents send letters, certified mail, postcards, and document packets. mailbox.bot prints, stamps, mails, photographs, tracks, and returns proof. Agent mailboxes are live now: a real street address plus PMB at the staffed, USPS-compliant Manhattan Beach, CA facility, **$15/mo**. The PMB number is assigned after USPS Form 1583 verification. The online notary fee is waived. Outbound mail uses prepaid credits and has no monthly base fee. - **Website:** https://mailbox.bot - **Install:** https://mailbox.bot/mcp-install - **Pricing:** https://mailbox.bot/pricing - **Public tool catalog:** https://mailbox.bot/api/mcp/tools-public - **OpenAPI:** https://mailbox.bot/openapi.json and https://mailbox.bot/openapi.yaml - **Registry:** [`bot.mailbox/mailbox`](https://registry.modelcontextprotocol.io) (DNS-verified on `mailbox.bot`) ## Connect **Sign in, no key.** Clients that support MCP sign-in (claude.ai, ChatGPT, Cursor, Claude Code) can add `https://mailbox.bot/api/mcp` with no headers. The first tool call opens mailbox.bot's sign-in page, where you choose the agent and Sandbox or Live. On a live connection each letter waits for your approval in the dashboard. Disconnect any time on the API Keys page. **Plugin.** This repository is also a Cursor and Claude Code plugin: `.cursor-plugin/plugin.json` and `mcp.json` for Cursor, `.claude-plugin/` and `.mcp.json` for Claude Code (`/plugin marketplace add arbengine/mailbox-mcp`, then `/plugin install mailbox-bot@mailbox-bot`). Both connect by sign-in and bring the `skills/mailbox-bot` skill. **With a key.** Add the hosted URL to the MCP client and pass a bearer key. Customers do not run a local process. ```json { "mcpServers": { "mailbox-bot": { "url": "https://mailbox.bot/api/mcp", "headers": { "Authorization": "Bearer sk_agent_YOUR_KEY_HERE" } } } } ``` Create an account at [mailbox.bot/signup](https://mailbox.bot/signup). A live agent key (`sk_agent_`) sends real mail and spends prepaid credits. A sandbox key (`sk_agent_test_`) rehearses on the same endpoint with no charge and no physical mail. A member account key (`sk_live_`) cannot send mail. ## Pricing | Plan | Price | What you get | |---|---|---| | Outbound mail and forwarded inbound context | $0/mo | Print and mail with prepaid credits. Forward scans, photos, and PDFs from an address you already control. | | Mailing address | $15/mo | Street address plus PMB at the Manhattan Beach, CA facility. Live now. The PMB number is assigned after USPS Form 1583 verification. | Published outbound examples start at $2.00 for a 1-page USPS First-Class letter. A dry run returns the exact price for that document, page count, service, and ZIP. That `cost_breakdown` is the price that applies. ## Tools 55 hosted tools. Current tools are listed first. A deprecated tool is still served and names its replacement. Live schemas: [public catalog](https://mailbox.bot/api/mcp/tools-public). | Tool | Description | |---|---| | `get_mailbox` | Read the account mailing address: street address plus PMB at the Manhattan Beach, CA facility. The rental is $15/mo and mailboxes are live now. The PMB number is assigned after USPS Form 1583 verification. | | `get_usage` | Read usage events and the prepaid credit balance. Agents can read the balance and cannot buy credits. | | `list_inbound_forwarding_addresses` | List the member's intake aliases on `forward.mailbox.bot` for scans, photos, and PDFs from an address the operator already controls. | | `list_inbound_mail` | List forwarded inbound mail with compact draft context for a reply. | | `get_inbound_mail` | Read one forwarded inbound item, OCR-backed facts, reply hints, and thread linkage. | | `list_postal_threads` | List physical-mail threads that group inbound context and outbound sends. | | `get_postal_thread` | Read one physical-mail thread and its timeline. | | `get_mailbox_md` | Read this agent's versioned MAILBOX.md instructions before an outbound send. | | `propose_mailbox_md_edit` | Propose an edit to standing instructions. The owner accepts or rejects it. | | `send_facility_message` | Send a message to the facility handling this mailbox. | | `list_facility_conversations` | List conversations with the facility. | | `get_facility_messages` | Read messages in a facility conversation. | | `update_webhook` | Update the legacy agent webhook callback URL and event subscriptions. | | `send_outbound_mail` | Print and mail a document with prepaid credits. Call with `dry_run=true` and show the price before a live send. | | `list_outbound_mail` | List outbound mail jobs and their status. | | `get_outbound_mail` | Read one outbound job, including cost, status, and fulfillment photos. | | `cancel_outbound_mail` | Cancel queued mail before printing and return eligible prepaid credits once. | | `create_test_outbound_mail` | Create a sandbox outbound record with no charge and no physical mail. | | `advance_test_outbound_mail` | Advance a sandbox outbound record through submitted, ready, mailed, and delivered. | | `quote_outbound_mail` | Price a letter before you have the document: mail class, pages, colour and, for FedEx, the ZIP. Needs no account. | | `send_text_letter` | Mail a letter written as plain text. Goes through `send_outbound_mail` with the same approval, caps and proof. | | `estimate_batch_mail` | Price a batch of postcards, letters, flyers or pamphlets (10 to 10,000 pieces) before any file exists. Printing and USPS postage included. | | `create_batch_mail` | Create a batch draft from a template link (a PDF, or a PNG/JPG postcard graphic) and recipients inline or by CSV link. Nothing is charged; the exact price comes back with `links.proof`. | | `get_batch_mail_proof` | A one-hour link to a proof PDF: the template as it prints, then the address label for one recipient at its real size, for the person who checks the batch. | | `confirm_batch_mail` | Pay for a draft from prepaid credits once and queue it for printing. The key's approval and daily-piece policies apply; `max_cost_cents` refuses before any debit. | | `get_batch_mail` | Read a batch: status, recipient summary, pricing and refunds, links, first 50 pieces. | | `list_batch_mail` | List the caller's batches, newest first. Sandbox keys see sandbox batches only. | | `cancel_batch_mail` | Cancel a batch before the facility starts; credits are refunded in full. | | `advance_test_batch_mail` | Sandbox only: move a batch submitted → in_progress → completed and fire `batch.completed`, as the facility would. | | `search_inbound_items` | Search physical mail at an assigned PMB, including saved OCR text. A sandbox key sees the account's Mojave sample letter. | | `get_inbound_item` | Read one inbound item: pages, actions, and current scan and forward quotes. | | `get_inbound_pages` | Read page text for one inbound item. | | `quote_inbound_forward` | Price every forwarding class for one item to a US ZIP. | | `request_inbound_action` | Propose scan, forward, or discard. The owner approves. The proposal does not spend credits or move mail by itself. | | `get_inbound_activity` | Read the inbound timeline for items this key can see. | | `list_webhook_endpoints` | List the member's webhooks. Signing secrets are omitted. | | `create_webhook_endpoint` | Create a webhook. The signing secret is returned once. | | `update_webhook_endpoint` | Update a webhook URL, events, keyword rules, or status. | | `test_webhook_endpoint` | Queue a synthetic `webhook.test` delivery. | | `test_webhook_endpoint_with_sample` | Test a webhook with the member's sample letter. | | `rotate_webhook_endpoint_secret` | Rotate a webhook signing secret after the operator asks. | | `list_webhook_deliveries` | Read recent webhook deliveries. Payloads omit page text. | | `replay_webhook_delivery` | Retry a failed webhook delivery. | | `list_agent_inbox` | Deprecated. Use `search_inbound_items`. | | `get_agent_inbox_context` | Deprecated. Use `get_inbound_item`. | | `get_agent_inbox_sources` | Deprecated. Use `get_inbound_item`. | | `list_agent_inbox_scans` | Deprecated. Use `get_inbound_pages`. | | `get_agent_inbox_scan` | Deprecated. Use `get_inbound_pages`. | | `get_agent_inbox_activity` | Deprecated. Use `get_inbound_activity`. | | `report_agent_inbox_outcome` | Deprecated. No successor. Still served until the alias window closes. | | `get_agent_inbox_handling` | Deprecated. Use `get_inbound_item`. | | `propose_agent_inbox_handling` | Deprecated. Use `request_inbound_action`. | | `seed_agent_inbox_sandbox` | Deprecated. No successor. Still served until the alias window closes. | | `list_inbound_items` | Deprecated. Use `search_inbound_items`. | | `get_inbound_item_sources` | Deprecated. Use `get_inbound_item`. | ### `get_mailbox` Read the account mailing address: street address plus PMB at the Manhattan Beach, CA facility. The rental is $15/mo and mailboxes are live now. The PMB number is assigned after USPS Form 1583 verification. ### `get_usage` Read usage events and the prepaid credit balance. Agents can read the balance and cannot buy credits. ### `list_inbound_forwarding_addresses` List the member's intake aliases on `forward.mailbox.bot` for scans, photos, and PDFs from an address the operator already controls. ### `list_inbound_mail` List forwarded inbound mail with compact draft context for a reply. ### `get_inbound_mail` Read one forwarded inbound item, OCR-backed facts, reply hints, and thread linkage. ### `list_postal_threads` List physical-mail threads that group inbound context and outbound sends. ### `get_postal_thread` Read one physical-mail thread and its timeline. ### `get_mailbox_md` Read this agent's versioned MAILBOX.md instructions before an outbound send. ### `propose_mailbox_md_edit` Propose an edit to standing instructions. The owner accepts or rejects it. ### `send_facility_message` Send a message to the facility handling this mailbox. ### `list_facility_conversations` List conversations with the facility. ### `get_facility_messages` Read messages in a facility conversation. ### `update_webhook` Update the legacy agent webhook callback URL and event subscriptions. ### `send_outbound_mail` Print and mail a document with prepaid credits. Call with `dry_run=true` and show the price before a live send. ### `list_outbound_mail` List outbound mail jobs and their status. ### `get_outbound_mail` Read one outbound job, including cost, status, and fulfillment photos. ### `cancel_outbound_mail` Cancel queued mail before printing and return eligible prepaid credits once. ### `create_test_outbound_mail` Create a sandbox outbound record with no charge and no physical mail. ### `advance_test_outbound_mail` Advance a sandbox outbound record through submitted, ready, mailed, and delivered. ### `quote_outbound_mail` Price a letter before you have the document: mail class, pages, colour and, for FedEx, the ZIP. Needs no account. ### `send_text_letter` Mail a letter written as plain text. Goes through `send_outbound_mail` with the same approval, caps and proof. ### `estimate_batch_mail` Price a batch of postcards, letters, flyers or pamphlets (10 to 10,000 pieces) before any file exists. Printing and USPS postage included. ### `create_batch_mail` Create a batch draft from a template link (a PDF, or a PNG/JPG postcard graphic) and recipients inline or by CSV link. Nothing is charged; the exact price comes back with `links.proof`. ### `get_batch_mail_proof` A one-hour link to a proof PDF: the template as it prints, then the address label for one recipient at its real size, for the person who checks the batch. ### `confirm_batch_mail` Pay for a draft from prepaid credits once and queue it for printing. The key's approval and daily-piece policies apply; `max_cost_cents` refuses before any debit. ### `get_batch_mail` Read a batch: status, recipient summary, pricing and refunds, links, first 50 pieces. ### `list_batch_mail` List the caller's batches, newest first. Sandbox keys see sandbox batches only. ### `cancel_batch_mail` Cancel a batch before the facility starts; credits are refunded in full. ### `advance_test_batch_mail` Sandbox only: move a batch submitted → in_progress → completed and fire `batch.completed`, as the facility would. ### `search_inbound_items` Search physical mail at an assigned PMB, including saved OCR text. A sandbox key sees the account's Mojave sample letter. ### `get_inbound_item` Read one inbound item: pages, actions, and current scan and forward quotes. ### `get_inbound_pages` Read page text for one inbound item. ### `quote_inbound_forward` Price every forwarding class for one item to a US ZIP. ### `request_inbound_action` Propose scan, forward, or discard. The owner approves. The proposal does not spend credits or move mail by itself. ### `get_inbound_activity` Read the inbound timeline for items this key can see. ### `list_webhook_endpoints` List the member's webhooks. Signing secrets are omitted. ### `create_webhook_endpoint` Create a webhook. The signing secret is returned once. ### `update_webhook_endpoint` Update a webhook URL, events, keyword rules, or status. ### `test_webhook_endpoint` Queue a synthetic `webhook.test` delivery. ### `test_webhook_endpoint_with_sample` Test a webhook with the member's sample letter. ### `rotate_webhook_endpoint_secret` Rotate a webhook signing secret after the operator asks. ### `list_webhook_deliveries` Read recent webhook deliveries. Payloads omit page text. ### `replay_webhook_delivery` Retry a failed webhook delivery. ### `list_agent_inbox` Deprecated. Use `search_inbound_items`. ### `get_agent_inbox_context` Deprecated. Use `get_inbound_item`. ### `get_agent_inbox_sources` Deprecated. Use `get_inbound_item`. ### `list_agent_inbox_scans` Deprecated. Use `get_inbound_pages`. ### `get_agent_inbox_scan` Deprecated. Use `get_inbound_pages`. ### `get_agent_inbox_activity` Deprecated. Use `get_inbound_activity`. ### `report_agent_inbox_outcome` Deprecated. No successor. Still served until the alias window closes. ### `get_agent_inbox_handling` Deprecated. Use `get_inbound_item`. ### `propose_agent_inbox_handling` Deprecated. Use `request_inbound_action`. ### `seed_agent_inbox_sandbox` Deprecated. No successor. Still served until the alias window closes. ### `list_inbound_items` Deprecated. Use `search_inbound_items`. ### `get_inbound_item_sources` Deprecated. Use `get_inbound_item`. ## What this repository is This repository holds the public [`server.json`](./server.json) manifest published to the official MCP Registry. The production server is hosted at `https://mailbox.bot/api/mcp`. [`server.js`](./server.js) lets a registry read the live tool catalog from `https://mailbox.bot/api/mcp/tools-public`. Authenticated tool calls use the hosted endpoint. Install steps for Claude, Cursor, and other clients are at [mailbox.bot/mcp-install](https://mailbox.bot/mcp-install). ## Verifying authenticity The namespace `bot.mailbox/*` is reserved via DNS proof on the apex domain `mailbox.bot`. Only the domain owner can publish servers under this namespace to the MCP Registry. The canonical manifest in this repo and the registry entry should match. ## License [MIT](./LICENSE) covers this manifest and the registry adapter. The mailbox.bot service is operated under the [mailbox.bot terms](https://mailbox.bot/terms).