MCP Server

The Lumbox MCP server gives AI tools direct access to email: create inboxes, wait for OTPs, send and reply, manage domains, webhooks and threads, store credentials, and drive a browser. The full list is below.

The claim_account tool creates a single-use, 15-minute dashboard link for an ownerless organization. Call it with a full organization API key and give the returned link to its human owner. Restricted keys cannot create links, and an existing user organization cannot be replaced.

Hosted transport is Streamable HTTP. Do not pick SSE.

If a client uses SSE against a JSON URL you get:

Could not connect to the MCP server or list its tools — SSE error: Invalid content type, expected "text/event-stream".

Switch the transport to Streamable HTTP and use a /mcp URL above.

Assistable (createassistants.com)

Integrations → MCP Servers → Add server:

https://api.lumbox.co/mcp works the same way. The REST root https://api.lumbox.co is not an MCP URL unless the client sends Streamable HTTP or Accept: text/event-stream.

Claude Code / Cursor / any HTTP client

Get an API key at app.lumbox.co → Settings → API Keys.

Claude Code (hosted HTTP):

claude mcp add --transport http lumbox https://mcp.lumbox.co/mcp

Then sign in, or send Authorization: Bearer ak_your_key_here.

Cursor / Claude Desktop / Windsurf — add to .cursor/mcp.json or claude_desktop_config.json:

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

Local stdio (npx)

For a local process instead of the hosted URL:

claude mcp add lumbox --env LUMBOX_API_KEY=ak_your_key_here -- npx -y @lumbox/mcp-server

{
  "mcpServers": {
    "lumbox": {
      "command": "npx",
      "args": ["-y", "@lumbox/mcp-server"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key_here",
        "LUMBOX_API_URL": "https://api.lumbox.co"
      }
    }
  }
}

Use it

Once connected, your AI agent can:

"Create an inbox called github-bot"
"Send an email to user@example.com saying hello"
"Wait for a verification email from github.com"
"What's the OTP code in my latest email?"

Environment Variables

Self-Hosted / Local Development

If you're running the API locally:

{
  "mcpServers": {
    "lumbox": {
      "command": "node",
      "args": ["/path/to/lumbox/apps/mcp-server/dist/index.js"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key_here",
        "LUMBOX_API_URL": "http://localhost:3001"
      }
    }
  }
}

Build first: cd apps/mcp-server && npx tsc

Authentication

Clients send a Bearer token:

Authorization: Bearer ak_your_key_here

OAuth 2.1 also works on the hosted URL. See authentication.

Session flow (Streamable HTTP)

1. Initialize - POST /mcp with Bearer token + initialize request
2. RPC calls - POST /mcp with Mcp-Session-Id header
3. Server messages - GET /mcp with Mcp-Session-Id (event stream for that session)
4. Terminate - DELETE /mcp with Mcp-Session-Id

Legacy SSE (GET /sse, then POST /messages) is accepted as a fallback. Prefer Streamable HTTP.

Docker

docker build -t lumbox-mcp apps/mcp-server/
docker run -p 3002:3002 -e LUMBOX_API_URL=http://api:3001 lumbox-mcp

Available Tools

Inbox Management

Email (Core Agent Tools)

Send / Reply / Forward

Threads

Domain Management

SMTP Configuration (BYOS)

Thread Routing

Webhooks

Browser Automation

See Browser Automation for details.

Skills (Compound Actions)

Credential Vault

See Credential Vault for security details.

Contact Lists & Marketing

AI Configuration (BYOK)