Connect an AI agent (MCP)

Let Claude Code and other agents create inboxes, wait for mail, and send replies. No API key.

Mailwurf runs an MCP server. Coding agents such as Claude Code connect to it by URL and get tools for inboxes and messages: create an inbox, wait for the verification mail, read the code, send a reply. The agent signs in with your Mailwurf account in the browser. You do not paste an API key into the agent.

Server URL

https://api.mailwurf.io/mcp

It is a remote MCP server over HTTP. The dashboard shows the same URL under AI agents.

Claude Code

Add the server:
```
claude mcp add --transport http mailwurf https://api.mailwurf.io/mcp
```
Add --scope user to use it in every project, or --scope project to share it with your team through .mcp.json.
Start Claude Code and run /mcp.
Select mailwurf and choose to authenticate. Your browser opens.
Sign in to Mailwurf and select Allow access.
Back in Claude Code, the server shows as connected. Ask it, for example, to "create a Mailwurf inbox and wait for the sign-up mail".

Other clients

Any client that can add a remote MCP server by URL can connect. Enter https://api.mailwurf.io/mcp as the server URL, with HTTP (streamable HTTP) as transport. Do not set a header or token; the client starts the sign-in itself.

Clients that read a JSON file usually take this shape:

{
  "mcpServers": {
    "mailwurf": {
      "type": "http",
      "url": "https://api.mailwurf.io/mcp"
    }
  }
}

Signing in

The first time the agent calls Mailwurf, it opens a browser window:

Sign in with your Mailwurf account, if you are not signed in already.
The page asks Allow … to use your Mailwurf inboxes? with the agent's name, and lists what it may do: read and wait for mail, send mail from your inboxes, and create and delete temporary inboxes.
Select Allow access. Decline sends the agent back without access.

The agent then acts as you, in the organizations you belong to. It sees the same inboxes as the dashboard and follows the same rules as the HTTP API.

Tools

Tool	What it does
`list_organizations`	Lists your organizations with slug, name, and role.
`list_inboxes`	Lists active inboxes, newest first.
`create_inbox`	Creates a temporary inbox. It expires after one hour.
`delete_inbox`	Deletes a temporary inbox. Permanent addresses stay.
`list_messages`	Lists messages of an inbox, newest first. Optional `subject` and `after` filters.
`get_message`	Reads one message with sender, subject, text, links, and code.
`wait_for_message`	Waits on the server until a message arrives. Default 15 seconds, at most 120.
`send_message`	Sends mail from an inbox, with attachments if needed. See Sending.

Results are the same JSON as the HTTP API. Errors such as inbox not found or timeout come back to the agent as tool errors.

Your own mailbox

Agents can also work with a mailbox you already have, for example at Hetzner, IONOS or Strato. In the dashboard, open Inboxes, select Connect, pick your provider and enter the address and password. Use an app password if your provider offers one.

The mailbox then shows up in list_inboxes with kind connected, and the same tools read, wait for and send its mail:

Mailwurf fetches mail from your provider when the agent asks and keeps no copy.
list_messages shows the newest 25 messages of your inbox.
send_message sends right away through your provider, and a copy usually appears in your Sent folder. Most agents ask you before they send.
Mail can come from anyone. Do not let an agent follow instructions it finds in a message.

You can only connect a mailbox in the dashboard; agents never see the password. An organization can connect up to three mailboxes.

Organizations

Every tool takes an optional organization: the organization slug, as in the dashboard URL app.mailwurf.io/<slug>/….

One organization: leave it out.
Several organizations: pass it. Without it, the tool answers with the list of your slugs. Tell the agent which organization to use, or let it call list_organizations.

How access ends

The agent gets an access token for one hour and renews it on its own.
The agent stays signed in. When its access expires, it asks you to sign in again.
To disconnect sooner, remove the server from the agent, for example claude mcp remove mailwurf.

Limits

The client must support the current MCP sign-in, where the client identifies itself by a URL. Claude Code does. Clients that only support registering themselves at the server cannot connect.
New account? Sign-up ends with the email confirmation. After you confirm your email, start the connection again from the agent (in Claude Code: /mcp, then authenticate).
Each user can hold four waits open at once, like an API key.
Tests in CI should keep using an API key. The MCP server is for agents that work on your behalf.

Connect an AI agent (MCP)

On this page