Mailbox MCP
Connect a mailbox
All documentation
Connect a mailbox Client not listed? Ask us
On this page

Set-up documentation

Connect your mailbox to Claude Code

One command adds the mailbox to Claude Code, and the scope flag is the part everyone gets wrong: local is the default, so it vanishes in the next project.

Time About 1 minute
Where claude mcp add, then /mcp to sign in
It needs URL only, then sign in
Top-level key mcpServers
URL key url

One command

Run this once, from anywhere. It does not matter which directory you are in, which is exactly what the scope flag is buying you.

Terminal Run once, anywhere 
claude mcp add --transport http --scope user \
  work-mail https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY

Replace work-mail with a name you will recognise. Unlike the chat clients, this one is read by a machine as well as by you: it becomes the identifier the tools are namespaced under, so keep it to letters, numbers and hyphens and it will need no quoting in any shell.

The scope flag, which is the whole trap

Claude Code has three scopes for an MCP server, and local is the default. That is the one detail worth reading this page for, because the failure it produces looks nothing like a configuration mistake.

Scope Where it applies Use it when
local This project only, and only for you. The default. Almost never, for a mailbox.
user Every project, for you. This is the one you want.
project This project, for everybody who checks it out. A shared mailbox on a team repository.

Leave the flag off and the mailbox works perfectly in the directory you set it up in, and is simply absent everywhere else, with no error and nothing in the tool list to explain it. It reads as the server having stopped working rather than as the server not being there.

Signing in

Adding the server does not authenticate it. Start Claude Code and run:

Inside Claude Code Once per connector 
/mcp

Choose your connector and then choose to authenticate. It opens the control panel in your browser, you sign in, and it asks which mailbox this connector should open. Claude Code stores its own credential afterwards, so this happens once. There is no client ID and no secret to paste anywhere: the server registers the client itself.

On a machine with no browser

A build agent or a headless box cannot complete a sign-in. Add the connector with an access token from the control panel instead, using --header "Authorization: Bearer YOUR-ACCESS-TOKEN", and skip the /mcp step. Do not put a token in a repository.

Or commit it to the project

With --scope project the entry goes into a .mcp.json at the repository root, which anybody who checks out the project will be prompted to trust. The file looks like this, and you can write it by hand instead of running the command:

.mcp.json Repository root 
{
  "mcpServers": {
    "work-mail": {
      "type": "http",
      "url": "https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY"
    }
  }
}

No credential in it, which is the point: everybody who checks it out signs in as themselves and opens their own mailbox. The file describes where the server is, not who anybody is.

Check that it worked

Try this first

Check my inbox for anything about this repository in the last fortnight and summarise what people asked for.

Worth more than a plain listing in a terminal agent, because it is the thing Claude Code is uniquely placed to do: the bug report and the code in one context. Nothing is marked read by asking.

/mcp also lists what is connected and its state, which is the quickest way to tell "not authenticated" apart from "not added in this scope".

The free tier is 5 MCP calls a day on any mailbox, with no card, which is enough to run the command above and see it answer.

Connect a mailbox Sign in

Where to go next

Claude.ai and the desktop app share one connector list and need doing once between them; the terminal keeps its own, which is why this is separate.

The tool reference matters more here than in a chat client: the read tools carry readOnlyHint, so an agent configured to auto-approve reads will run them without asking, and every one of those still counts as a call against your daily limit.

Read 30 August 2026 Every value on this page came off Claude Code documentation: MCP on that day. The old docs.claude.com path 301s here. If it has changed since, tell us and we will read it again.

By Mark McNeece, Founder Published Last reviewed Editorial standards