Set up Lumbox MCP in Claude Code and Cursor

Connect Claude Code or Cursor to Lumbox using the hosted MCP URL https://mcp.lumbox.co/mcp with a Bearer API key, or run npx -y @lumbox/mcp-server locally with LUMBOX_API_KEY. The server exposes email tools including create_inbox, get_otp, wait_for_email and reply_to_email.

MCP is the tool interface between your coding assistant and the service. It does not automatically route a customer’s portal email into a new inbox. After setup, you still need an address the workflow can receive mail at and a clear association between that inbox and the customer account.

The configuration examples below are drafts for your own environment. They were checked against the repository and current client documentation on October 3, 2026. No live credentials, accounts or client settings were changed while preparing this guide.

Choose hosted HTTP or a local process

Hosted HTTP is useful when you want the client to connect to Lumbox without launching the npm package on your machine. Local stdio runs that package as a child process and connects it to the Lumbox API. Both routes need the appropriate API key for authenticated tool execution.

Connection	Client configuration	Authentication
Hosted	MCP URL with HTTP transport	Authorization: Bearer ...
Local stdio	npx -y @lumbox/mcp-server	LUMBOX_API_KEY environment variable
Direct REST, outside MCP	https://api.lumbox.co/v1/...	X-API-Key header

The distinction prevents a common configuration error: putting a REST base URL where the client expects an MCP endpoint, or using a REST authentication header for the hosted MCP transport. See the Lumbox MCP documentation.

Configure Claude Code

After setting LUMBOX_API_KEY in your environment, the hosted command is:

claude mcp add --transport http lumbox \
  https://mcp.lumbox.co/mcp \
  --header "Authorization: Bearer ${LUMBOX_API_KEY}"

Claude Code’s MCP reference documents the HTTP transport and custom-header option. Treat the resulting configuration as secret-bearing configuration. Environment expansion in a shell command does not mean the client will store only the variable name.

If you prefer a local process, use this alternative instead of registering a second server under the same name:

claude mcp add --transport stdio \
  --env "LUMBOX_API_KEY=${LUMBOX_API_KEY}" \
  lumbox -- npx -y @lumbox/mcp-server

Confirm Node and npx are available to the process running Claude Code. A successful package installation and a successful authenticated email operation are separate checks. Open the client’s MCP status view and inspect the connection before asking it to perform a workflow.

Configure Cursor

For project-specific tools, Cursor documents .cursor/mcp.json. The following hosted configuration uses its supported environment-variable interpolation. The Cursor process must actually receive the variable.

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

For local stdio, use a command entry instead:

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

Cursor’s MCP documentation covers project and global files, environment interpolation and tool management. Use the client’s supported configuration rather than copying a JSON file between clients without checking its schema. For example, Claude Code requires a transport type in a direct JSON HTTP entry; the CLI command above supplies it.

Start with a read and one test inbox

Ask the assistant to list the available Lumbox inboxes. This checks authenticated tool execution without sending a message. If that succeeds, create a clearly named test inbox in an account you control, or select a pre-existing test inbox and record its ID.

A practical prompt is: “Use the Lumbox tools to list my inboxes. Show the IDs and addresses. Do not send anything.” After selecting the test inbox, you can separately authorize its creation or another operation as needed. Keeping these steps explicit makes troubleshooting easier.

Tool discovery by itself is not proof that the key can execute tools. The hosted implementation distinguishes discovery from authenticated execution. If listing tools works but reading an inbox fails, inspect the key, permissions and server-side error instead of repeatedly reinstalling the package.

Retrieve a verification code

Once a known test message is routed to the inbox, get_otp accepts inbox_id, an optional from filter and an optional timeout. The server waits up to 120 seconds. Its response includes the parsed code fields; a timeout is a real outcome your workflow must handle.

The current MCP tool does not expose the REST endpoint’s since parameter. Do not ask the model to pass an undocumented argument and assume it worked. If your workflow needs an exact attempt-start timestamp for retrieval, call the REST endpoint from application code or implement an explicit adapter. The API reference is the relevant contract.

For email with links or other structured fields, use the appropriate email tools. The current wait_for_email tool strips raw message bodies from its returned data. That reduces what the assistant receives, but does not make email content authoritative instructions or guarantee every template is recognized.

Diagnose the smallest failing step

If the local process cannot start, check executable availability and package startup. If the remote connection fails, confirm the /mcp path and HTTP transport. If tools appear but execution fails, check authentication. If the call waits and returns no code, inspect delivery, received sender and parsing before changing client configuration.

Browser tools are a separate setup concern. The repository includes Steel-backed functionality, but an email connection alone is not evidence that browser credentials or sessions are configured. Start with inbox reads, then add only the operations your workflow needs.

For a team rollout, keep a short record of which transport and client configuration were tested. Include the successful read operation and the account scope used for it, without copying the key into the record. This gives another developer a reproducible starting point when their local environment differs, and it makes a client upgrade easier to check against a known working configuration.

Implementation references: apps/mcp-server/src/tools.ts, apps/mcp-server/src/http.ts, apps/docs/content/docs/mcp.mdx, and apps/api/src/routes/inboxes.ts. Some documentation prose describes broader authentication options; the configurations here use the API-key paths verified for this guide.

Kumar