MCP Server

The Lumbox MCP server gives AI tools direct access to email: create inboxes, wait for OTPs, send and reply, drive a browser. 103 tools.

Hosted transport is Streamable HTTP. Do not pick SSE.


URL	`https://mcp.lumbox.co/mcp`
Also	`https://api.lumbox.co/mcp`
Transport	Streamable HTTP
Auth	`Authorization: Bearer ak_...`

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:

Field	Value
Name	`Lumbox`
Server URL	`https://mcp.lumbox.co/mcp`
Transport	Streamable HTTP
Auth token	your `ak_...` key (sent as Bearer)

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

Variable	Default	Description
`LUMBOX_API_KEY`	(required)	Your API key (`ak_...`)
`LUMBOX_API_URL`	`https://api.lumbox.co`	API server URL
`STEEL_API_URL`	(required for browser)	Steel Browser URL (e.g. `http://localhost:3000`)
`STEEL_API_KEY`	(optional)	Steel API key if auth is enabled

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)

Initialize - POST /mcp with Bearer token + initialize request
RPC calls - POST /mcp with Mcp-Session-Id header
Server messages - GET /mcp with Mcp-Session-Id (event stream for that session)
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 (103)

Inbox Management

Tool	Description
`create_inbox`	Create a new email inbox (returns email address)
`list_inboxes`	List your inboxes, newest first (paginated: `limit`, `cursor`)
`get_inbox`	Get inbox details and email count
`delete_inbox`	Delete an inbox and all its emails

Email (Core Agent Tools)

Tool	Description
`wait_for_email`	Block until a matching email arrives (with filters)
`get_otp`	Get the latest OTP/verification code
`list_emails`	List emails with filters (sender, category, date)
`read_email`	Read full email with parsed OTP, links, summary
`search_emails`	Search across all inboxes

Send / Reply / Forward

Tool	Description
`send_email`	Send an email from an inbox
`reply_to_email`	Reply with auto-threading headers
`forward_email`	Forward an email to another address

Threads

Tool	Description
`list_threads`	List conversation threads
`get_thread`	Get all emails in a thread

Domain Management

Tool	Description
`add_domain`	Add a custom domain (returns DNS records)
`verify_domain`	Check DNS and activate domain
`list_domains`	List all domains

SMTP Configuration (BYOS)

Tool	Description
`configure_smtp`	Configure outbound SMTP provider
`list_smtp_configs`	List SMTP configurations
`test_smtp_config`	Test an SMTP config

Thread Routing

Tool	Description
`assign_thread`	Assign an agent to a thread
`unassign_thread`	Remove an agent from a thread
`list_thread_agents`	List agents on a thread
`create_routing_rule`	Auto-route emails by sender/subject/category
`list_routing_rules`	List routing rules
`delete_routing_rule`	Delete a routing rule

Webhooks

Tool	Description
`create_webhook`	Register a webhook for email events
`list_webhooks`	List webhooks
`test_webhook`	Test a webhook
`delete_webhook`	Delete a webhook

Browser Automation

Tool	Description
`browser_navigate`	Navigate to URL, returns accessibility tree
`browser_snapshot`	Get current page state with element refs
`browser_click`	Click element by ref (@e1, @e2...)
`browser_type`	Type text into input by ref
`browser_select`	Select dropdown option
`browser_eval`	Run JavaScript on page
`browser_screenshot`	Take screenshot
`browser_save_state`	Save cookies + localStorage
`browser_load_state`	Restore saved session
`browser_close`	Close browser session

See Browser Automation for details.

Skills (Compound Actions)

Tool	Description
`skill_signup_with_email`	Navigate + fill email + submit + wait for OTP - all in one call
`skill_login_with_email`	Navigate + enter email + submit + wait for magic link/OTP
`skill_verify_email`	Wait for verification email + click the link

Credential Vault

Tool	Description
`store_credential`	Securely store a password/API key/TOTP secret (encrypted, never returned)
`login_with_credential`	Auto-inject credentials into login form via Steel (fields blurred, auto-submit)
`use_credential_in_browser`	Fill credential into a specific form field (for non-login fields)
`list_credentials`	List stored credentials (metadata only, never values)
`delete_credential`	Permanently delete a credential

See Credential Vault for security details.

Contact Lists & Marketing

Tool	Description
`create_contact_list`	Create a contact list for marketing
`list_contact_lists`	List contact lists
`add_contacts`	Add contacts to a list
`list_contacts`	List contacts in a list
`remove_contact`	Remove a contact
`delete_contact_list`	Delete a contact list
`send_marketing_email`	Send to all contacts in a list

AI Configuration (BYOK)

Tool	Description
`configure_ai`	Set up AI provider and API key
`get_ai_config`	View AI configuration

MCP Server

On this page