> ## Documentation Index
> Fetch the complete documentation index at: https://inbound.new/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, ChatGPT, Cursor, OpenCode and other AI agents to Inbound, and give agents their own mailboxes

Inbound's MCP (Model Context Protocol) server lets AI assistants manage your domains, endpoints, addresses, emails and Guard rules. It can also create **mailboxes**: virtual email accounts that an agent can read, reply from and send from.

**Server URL:** `https://inbound.new/mcp`

## Connect

### With OAuth (recommended)

Add the URL to your client. When it connects, it opens Inbound in your browser; sign in and approve access. No API key needed.

```bash Claude Code theme={null}
claude mcp add --transport http inbound https://inbound.new/mcp
```

```json Cursor (.cursor/mcp.json) theme={null}
{
  "mcpServers": {
    "inbound": { "type": "http", "url": "https://inbound.new/mcp" }
  }
}
```

```json OpenCode (opencode.json) theme={null}
{
  "mcp": {
    "inbound": { "type": "remote", "url": "https://inbound.new/mcp" }
  }
}
```

In Claude.ai and ChatGPT, add a custom connector with the same URL.

OAuth grants full access to your account, the same as an API key. The approval screen names the app and where it will send you back to; only approve apps you started the connection from.

### With an API key

For scripts and clients without OAuth, send an API key from [settings](https://inbound.new/settings) as a bearer token:

```json theme={null}
{
  "mcpServers": {
    "inbound": {
      "type": "http",
      "url": "https://inbound.new/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

The `x-inbound-api-key` header also works. Clients that only support STDIO can bridge with `npx mcp-remote https://inbound.new/mcp --header "Authorization:Bearer ${INBOUND_API_KEY}"`.

## Give an agent its own mailbox

1. Ask your assistant to create a mailbox, e.g. *"Create a mailbox for [agent@yourdomain.com](mailto:agent@yourdomain.com) called Support Agent"*. This calls `create_mailbox`, which returns a password shown once.
2. Connect the agent to `https://inbound.new/mcp` with `Authorization: Bearer <mailbox password>`.
3. The agent now has one email account: it can check its inbox, read, reply, send and archive. It can't see other mail in your account or send as any other address. The Inbound API enforces this.

The same mailbox password works over [IMAP](https://inbound.new/docs/mailboxes/connect-imap.md) and [SMTP](https://inbound.new/docs/mailboxes/connect-smtp.md), and the mailbox appears in the [dashboard](https://inbound.new/mailboxes). The address must be on a verified domain; new accounts can use their instant `*.inbnd.dev` domain.

### Mailbox tools

| Tool | Description |
| - | - |
| `whoami` | The mailbox's address, sending identity, scopes and unread count |
| `list_messages` | Inbox, archive or sent folder, with `unread_only` and search |
| `read_message` | Full message; marks it read |
| `update_message` | Mark read/unread, archive/unarchive |
| `get_thread` | The whole conversation |
| `reply` | Reply to a received message, threaded |
| `send_email` | Send a new email as the mailbox |
| `download_attachment` | Fetch an attachment |

The mailbox password also gets the folder, folder-message, filter, spam and activity tools listed under [Account tools](#account-tools), without a `mailbox_id` input, plus `rotate_my_password`. Filters, spam settings, activity and password rotation each need the matching `selfService` flag on the credential (`filters`, `spam`, `activity`, `password`); otherwise the API returns `403`. See [Access and limits](https://inbound.new/docs/mailboxes/access-and-limits.md#self-service).

Mailbox read/unread and archive actions update the same folders and flags used by IMAP and the [HTTP mailbox API](https://inbound.new/docs/mailboxes/http-api.md), not the dashboard's separate account-level markers. Messages keep the `inbox`, `archive` and `sent` folder values; `folderPath` gives the exact folder when needed.

Immediate sends and replies from a **Read & write** mailbox save a copy to its `Sent` folder a few seconds after the send returns. Account-key sends and replies also save to enabled read/write mailboxes whose sending address (or login email, when no sending address is set) exactly matches the From address; a matching domain scope is not enough. Scheduled sends and older account sent records are not copied, and a failed copy never resends the email. See [Sent copies](https://inbound.new/docs/mailboxes/http-api.md#sent-copies).

## Account tools

Connected with OAuth or an API key, the server exposes 78 tools:

| Area | Tools |
| - | - |
| Domains | `list_domains`, `get_domain`, `create_domain`, `update_domain`, `delete_domain`, `enable_domain_dkim` |
| Endpoints | `list_endpoints`, `get_endpoint`, `create_endpoint`, `update_endpoint`, `delete_endpoint`, `test_endpoint` |
| Addresses | `list_email_addresses`, `get_email_address`, `create_email_address`, `update_email_address`, `delete_email_address` |
| Emails | `list_emails`, `get_email`, `send_email`, `reply_to_email`, `update_email`, `cancel_scheduled_email`, `pause_scheduled_email`, `resume_scheduled_email`, `retry_email_delivery`, `list_threads`, `get_thread`, `list_attachments`, `download_attachment` |
| Mailboxes | `list_mailboxes`, `create_mailbox`, `update_mailbox`, `delete_mailbox`, `rotate_mailbox_password`, `get_mailbox`, `list_mailbox_messages`, `read_mailbox_message`, `update_mailbox_message`, `get_mailbox_thread`, `send_from_mailbox`, `reply_from_mailbox`, `download_mailbox_attachment` |
| Mailbox folders | `list_mailbox_folders`, `create_mailbox_folder`, `rename_mailbox_folder`, `delete_mailbox_folder` |
| Folder messages | `list_folder_messages`, `get_folder_message`, `get_folder_message_raw`, `set_message_flags`, `move_message`, `copy_message`, `delete_folder_message`, `expunge_folder`, `append_message`, `list_folder_message_attachments`, `download_folder_message_attachment` |
| Mailbox filters | `list_mailbox_filters`, `get_mailbox_filter`, `create_mailbox_filter`, `update_mailbox_filter`, `delete_mailbox_filter`, `reorder_mailbox_filters`, `apply_mailbox_filters` |
| Mailbox spam | `get_mailbox_spam_settings`, `set_mailbox_spam_settings`, `add_spam_list_entry`, `remove_spam_list_entry` |
| Mailbox activity | `list_mailbox_activity`, `list_account_activity` |
| Guard | `list_guard_rules`, `get_guard_rule`, `create_guard_rule`, `update_guard_rule`, `delete_guard_rule`, `check_guard_rule`, `generate_guard_rule` |

`update_mailbox` and `create_mailbox` also take the [access controls](https://inbound.new/docs/mailboxes/access-and-limits.md): `protocols`, `allowed_ips`, `storage_quota_bytes`, `daily_send_limit` and `self_service`. Folder tools work on the same folders, UIDs and flags as IMAP and the [HTTP mailbox API](https://inbound.new/docs/mailboxes/http-api.md); moving a message into `Junk` or back to `INBOX` marks it as junk or not junk for that mailbox only. Filters run on new mail; `apply_mailbox_filters` processes mail already in a folder. Activity tools return sign-ins, refused sign-ins, IMAP session events, quota errors and send failures for the last 30 days, never message content or passwords.

To expose fewer tools, add `?toolsets=` with any of `domains,endpoints,addresses,emails,mailboxes,guard`, for example `https://inbound.new/mcp?toolsets=mailboxes,emails`.

## Example prompts

* "Show me unread email to [support@mydomain.com](mailto:support@mydomain.com)"
* "Create a webhook endpoint for [https://example.com/hooks](https://example.com/hooks) and route [orders@mydomain.com](mailto:orders@mydomain.com) to it"
* "Create a mailbox for [agent@mydomain.com](mailto:agent@mydomain.com) and give me its MCP config"
* "Reply to the last email from [jane@example.com](mailto:jane@example.com) saying we'll ship Friday"
* "Block cold sales outreach with a Guard rule"
* "Add a filter to the support mailbox that moves invoices from [billing@vendor.com](mailto:billing@vendor.com) into Finance"
* "Show failed sign-ins for [agent@mydomain.com](mailto:agent@mydomain.com) this week"

The server is open source: [inboundemail/mcp](https://github.com/inboundemail/mcp).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.