# Connect to aktmail

This is the setup guide for aktmail. aktmail gives agents real email over
MCP. Agents receive mail at unguessable addresses and send mail with scoped
permission.

- MCP endpoint: `https://api.akt.sh/mcp` (streamable HTTP)
- Credentials: an OAuth sign-in (recommended), or an `akm_` API key
- Scopes: `read`, `send`, `manage`

## If you are an agent

1. Ask your user to create an account at `https://api.akt.sh/signup` first. Then
   ask your user to complete the OAuth sign-in. If OAuth does not fit, ask
   your user for an `akm_` API key. Do not guess a credential.
2. Add the endpoint to the MCP configuration of your harness. Use the steps
   below.
3. Call the `whoami` tool to confirm the connection.

A first-time user needs more time to connect. The sign-up has more steps
than a sign-in, for example email verification. Wait for your user, and do
not retry the connection during the sign-up. A retry can open a new
sign-in window and interrupt the sign-up. GitHub Copilot in VS Code does
this. If that happens, ask your user to finish the sign-up at
`https://api.akt.sh/signup`. Then start the connection once.

## Set up with OAuth (recommended)

The client needs only the URL. aktmail publishes the OAuth metadata, so the
client finds the sign-in endpoints itself. No secret goes in a config file.
At sign-in, the user selects the scopes. Give an agent `read` only,
unless it must send.

Tell your user to create the account at `https://api.akt.sh/signup` first. With
a ready account, the client sign-in is one click. Some clients restart
the connection when the sign-up takes too long.

### Claude Code

```sh
claude mcp add --transport http aktmail https://api.akt.sh/mcp
```

Then run `/mcp` inside Claude Code. Complete the sign-in.

### Claude (claude.ai and the desktop app)

1. Open **Settings → Connectors → Add custom connector**.
2. Enter the name `aktmail` and the URL `https://api.akt.sh/mcp`.
3. Click **Connect**.
4. Complete the sign-in.

### ChatGPT

1. Open **Settings → Apps & Connectors**. Enable **Developer mode**. Then
   click **Create**.
2. Enter the MCP server URL `https://api.akt.sh/mcp`. Select **OAuth**. Keep the
   client id and secret blank. Select **CIMD** as the registration method.
3. Complete the sign-in on the `/authorize` page. Select the scopes.

### Cursor

Add to `.cursor/mcp.json` in the project, or to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "aktmail": { "url": "https://api.akt.sh/mcp" }
  }
}
```

Cursor shows a sign-in prompt next to the server. Complete it.

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json`, or to the user-level MCP configuration:

```json
{
  "servers": {
    "aktmail": { "type": "http", "url": "https://api.akt.sh/mcp" }
  }
}
```

VS Code starts the sign-in when it connects to the server. On a retry it
opens a new sign-in window. If windows keep opening during your sign-up,
finish the sign-up at `https://api.akt.sh/signup` first. Then connect again.

### netclaw

```sh
netclaw mcp add aktmail https://api.akt.sh/mcp
netclaw mcp auth aktmail
```

The first command writes the server to `~/.netclaw/config/netclaw.json`.
The second command starts the sign-in in a browser. netclaw runs as a
daemon. On a host without a browser, use an API key instead.

### Other OAuth clients

A client that supports MCP OAuth needs only the URL. When a request has no
credentials, aktmail sends the standard challenge that starts OAuth
discovery. For a client that can only start stdio servers, use
`mcp-remote` as a bridge. It runs the OAuth flow in a browser:

```json
{
  "mcpServers": {
    "aktmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.akt.sh/mcp"]
    }
  }
}
```

## Set up with an API key

An `akm_` API key is a bearer token for the `Authorization` header.
Use a key only when OAuth does not fit. The use cases:

- **No browser.** CI jobs, cron tasks, and servers cannot complete a
  browser sign-in. Store a key as a secret there.
- **No OAuth support in the client.** Examples: Windsurf, Codex CLI, and
  the Copilot coding agent on github.com.
- **Agent fleets.** A key can create narrower child keys with the
  `create_api_key` tool. An agent can give each sub-agent its own scoped
  key.
- **The REST API.** Scripts that call `/api/*` directly must send a key.
  OAuth tokens work only on `/mcp`.

To get a key, ask a connected agent to run `create_api_key`, or ask the
person who invited you. Give a key the smallest scopes and a short expiry.

### Claude Code

```sh
claude mcp add --transport http aktmail https://api.akt.sh/mcp \
  --header "Authorization: Bearer akm_..."
```

### Cursor and VS Code

Add a `headers` entry to the server configuration shown above:

```json
"headers": { "Authorization": "Bearer akm_..." }
```

### netclaw

Add the header to `~/.netclaw/config/secrets.json`:

```json
{
  "McpServers": {
    "aktmail": {
      "Headers": { "Authorization": "Bearer akm_..." }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "aktmail": {
      "serverUrl": "https://api.akt.sh/mcp",
      "headers": { "Authorization": "Bearer akm_..." }
    }
  }
}
```

### Copilot coding agent on github.com

Put the URL in the repo's Copilot → MCP settings. Store the key as a
`COPILOT_MCP_*` secret.

### Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.aktmail]
url = "https://api.akt.sh/mcp"
bearer_token_env_var = "AKTMAIL_TOKEN"
```

Set `AKTMAIL_TOKEN` to an `akm_` key in the environment that runs Codex.

### mcp-remote with a key

Add the header arguments to the bridge configuration shown above:

```json
"args": [
  "-y", "mcp-remote", "https://api.akt.sh/mcp",
  "--header", "Authorization: Bearer akm_..."
]
```

## Verify and use

Call `whoami`. The reply shows the identity, the tenant, and the scopes.
The mail tools are: `create_address`, `list_addresses`,
`disable_address`, `list_messages`, `get_message`, `get_attachment`,
`send_email`, `reply_to_message`, `mark_read`, `delete_message`.
Accounts with the `manage` scope get more tools.