The Lumbox MCP server gives an MCP client more than 80 tools for email: create an inbox, wait for a verification code, list and read messages, search, send, reply and forward, plus tools for domains, webhooks and browser sign-ups. This guide is the installation for Claude Code, Claude Desktop and Cursor, with the exact commands and config files, and the problems you are most likely to hit.

Hosted or local

There are two ways to run it, and they expose the same kind of tools.

  • Hosted: https://mcp.lumbox.co/mcp, over the Streamable HTTP transport. Nothing to install. Your client sends the API key as Authorization: Bearer ak_....
  • Local: npx -y @lumbox/mcp-server, which your client starts as a child process and talks to over stdio. It needs Node 18 or newer and reads the key from the LUMBOX_API_KEY environment variable.

Use hosted where the client lets you attach a header to a remote server, which of the three clients here means Claude Code and Cursor. Use local for Claude Desktop, for the reason explained below. Either way you need an API key: create one in the dashboard at app.lumbox.co under Settings, API Keys, or run npx lumbox signup to create a free organization from the terminal and get a key printed once.

Claude Code

Hosted:

claude mcp add --transport http lumbox https://mcp.lumbox.co/mcp \
  --header "Authorization: Bearer ak_your_key"

Local:

claude mcp add --env LUMBOX_API_KEY=ak_your_key --transport stdio lumbox \
  -- npx -y @lumbox/mcp-server

Everything after -- is the command Claude Code runs. Claude Code's docs recommend putting another option such as --transport stdio between --env and the server name, because --env accepts several KEY=value pairs and would otherwise try to read the name as one. Run /mcp inside a session, or claude mcp list in the shell, to see the server and its status.

To share the server with a team, add --scope project, which writes a .mcp.json file at the repository root. Do not commit a key in that file. Use "Authorization": "Bearer ${LUMBOX_API_KEY}" in its headers and let each person set the variable in their own shell.

Why pass the key as a header instead of signing in? Claude Code flags a remote server for OAuth sign-in when it answers with 401 or 403. Lumbox's hosted server deliberately lets the MCP handshake and the tool listing through without a credential, so that directories can read which tools it has. Without a header, Claude Code connects, lists the tools, and then every tool call fails with an authentication error. Lumbox does run an OAuth authorization server for MCP clients, which the OAuth for MCP servers post describes, but the header is the path that works without surprises.

Claude Desktop

Claude Desktop has two separate mechanisms. Its claude_desktop_config.json file lists local servers that the app starts on your machine. Remote servers are added as custom connectors in the app's connector settings, where you enter a URL. Connectors are reached from Anthropic's cloud and authenticate with OAuth, and the standard dialog has no field for pasting an API key. The simplest reliable setup is therefore the local server in the config file.

Open the file from Claude Desktop's settings (Developer, then Edit Config). It lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "lumbox": {
      "command": "npx",
      "args": ["-y", "@lumbox/mcp-server"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key"
      }
    }
  }
}

Quit Claude Desktop completely and reopen it. The app reads this file only at startup.

The most common failure here is Node. Claude Desktop does not load your shell profile, so if you manage Node with nvm, it can find an old system Node instead of the version your terminal uses. The server checks for this first and exits with a message saying it needs Node 18 or higher. The fix is to set "command" to the full path of npx inside a Node 18+ installation, which which npx in your terminal will print.

Cursor

Cursor reads ~/.cursor/mcp.json for servers available in every project and .cursor/mcp.json for one project. The hosted server takes a url and headers, and Cursor can fill the key from an environment variable:

{
  "mcpServers": {
    "lumbox": {
      "url": "https://mcp.lumbox.co/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LUMBOX_API_KEY}"
      }
    }
  }
}

For the local server, use the same command, args and env block as the Claude Desktop example. If the project file is committed, keep the key in the environment variable rather than in the file.

Check that it works

Ask the client something that needs exactly one tool: "Create a Lumbox inbox called setup-test and tell me its address." It should call create_inbox and come back with an address on trylumbox.com. Then ask it to wait up to two minutes for mail on that inbox, and send the address a message from your own mail account while it waits. wait_for_email only returns mail that arrives after the call starts, holds the request open for 30 seconds by default and up to 120, and returns the parsed fields of the message when it lands. If this is the first inbox in your organization, it also holds a welcome message from Lumbox, so "list the emails in that inbox" has something to show straight away; later inboxes start empty.

When it does not work

  • SSE error: Invalid content type, expected "text/event-stream": the client is set to the old SSE transport. Switch it to Streamable HTTP and use the /mcp URL.
  • The local server exits with "Missing or invalid API key": LUMBOX_API_KEY is unset or does not start with ak_. The stdio server accepts API keys only, not OAuth tokens.
  • The first start is slow or times out: the package installs Playwright's Chromium for its browser tools on first run, a download the server itself estimates at about 150 MB. Run npx -y @lumbox/mcp-server once in a terminal with the key set, let it finish, then restart the client.
  • Browser tools fail and email tools work: the browser tools drive a Steel browser server and need STEEL_API_URL set. Without it, only the email tools are usable.
  • A tool you read about is missing: the npm package and the hosted server are not always on the same version, so their tool lists can differ slightly.

Limit what the key can do

The MCP server has exactly the access of the key you give it. An organization key can read every inbox and change domains and webhooks. For a coding assistant working in one repository, create a project with POST /v1/projects, put the inboxes it needs in that project, and give the client a project key from POST /v1/projects/{id}/keys. That key only sees the project's inboxes and is refused on organization-level routes. Tools that need those routes will return an error instead of acting.

The full tool reference and the environment variables are on the MCP docs page. For running Claude against the hosted server from your own code, without a desktop app, see using Claude with MCP to read and send email.