Connect your AI assistant

Step-by-step setup for Claude, Claude Code, ChatGPT, Cursor, Codex, VS Code and any other MCP client.

On this page
  1. What you choose when connecting
  2. Claude (claude.ai and Claude Desktop)
  3. Claude Code
  4. ChatGPT
  5. Cursor
  6. OpenAI Codex
  7. VS Code
  8. Windsurf
  9. Any other MCP client
  10. Create an agent token
  11. Check that it works
  12. If something goes wrong

You can connect almost any AI assistant to Luminobot. There are two ways to do it:

  • Sign in (recommended). Assistants that support sign-in only need the server address. They open a Luminobot page where you choose what the assistant may do, then click Allow access. No token to copy or store.
  • Agent token. For assistants without sign-in, create a token on the AI agents (MCP) page and paste it into the assistant's settings.

Your MCP server address is:

https://app.luminobot.com/api/v1/mcp/

You also find it, with a Copy URL button, under Settings → AI agents (MCP).

What you choose when connecting

Whether you sign in or create a token, Luminobot asks the same questions:

  • Workspaces: tick the workspaces the assistant may work in.
  • What it can do: Read only, Reply & manage inbox, Full access, or Custom (pick the exact permissions). It never gets more than you have.
  • Sending and publishing: Drafts for approval (replies and posts wait for a person — the safe default) or Act directly.
  • Accounts: All accounts I can access (including ones connected later) or Only the accounts I pick.
  • Access expires: 30 days, 90 days (default), 1 year or never.

Not sure? Leave the defaults: inbox access with drafts for approval, expiring in 90 days. What MCP is explains the choices.

Claude (claude.ai and Claude Desktop)

  1. In Claude, open Settings → Connectors → Add custom connector.
  2. Name it Luminobot and paste the server address https://app.luminobot.com/api/v1/mcp/.
  3. Click Connect. A Luminobot page opens: sign in, choose what Claude may do and click Allow access.
  4. Back in Claude, start a chat and try "List my workspaces" or "Triage my inbox".

No token is needed. Older Claude Desktop versions without custom connectors can use the mcp-remote bridge in claude_desktop_config.json with an agent token (replace <YOUR_TOKEN>):

{
  "mcpServers": {
    "luminobot": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.luminobot.com/api/v1/mcp/",
        "--header",
        "Authorization:${LUMINOBOT_AUTH}"
      ],
      "env": {
        "LUMINOBOT_AUTH": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Claude Code

Run this in a terminal, with an agent token in place of <YOUR_TOKEN> (add --scope user to use it in every project):

claude mcp add --transport http luminobot https://app.luminobot.com/api/v1/mcp/ --header "Authorization: Bearer <YOUR_TOKEN>"

Prefer to sign in instead of using a token? Leave out the --header part:

claude mcp add --transport http luminobot https://app.luminobot.com/api/v1/mcp/

Then run /mcp inside Claude Code and choose Authenticate.

ChatGPT

  1. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
  2. Create a connector, paste the server address https://app.luminobot.com/api/v1/mcp/ and choose OAuth.
  3. Sign in to Luminobot, choose what ChatGPT may do and click Allow access.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "luminobot": {
      "url": "https://app.luminobot.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Leave out headers to sign in from Cursor's MCP settings instead.

OpenAI Codex

Add this to ~/.codex/config.toml:

[mcp_servers.luminobot]
url = "https://app.luminobot.com/api/v1/mcp/"
bearer_token_env_var = "LUMINOBOT_TOKEN"

# then, in your shell profile:
# export LUMINOBOT_TOKEN="<YOUR_TOKEN>"

Or sign in: codex mcp add luminobot --url https://app.luminobot.com/api/v1/mcp/, then codex mcp login luminobot.

VS Code

Add this to .vscode/mcp.json (or run "MCP: Add Server" and choose HTTP):

{
  "servers": {
    "luminobot": {
      "type": "http",
      "url": "https://app.luminobot.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Leave out headers and VS Code offers to sign in instead.

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "luminobot": {
      "serverUrl": "https://app.luminobot.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Any other MCP client

Luminobot works with any client that speaks MCP over Streamable HTTP:

  • URL: https://app.luminobot.com/api/v1/mcp/
  • Header: Authorization: Bearer <YOUR_TOKEN> (an agent token), or use OAuth sign-in if the client supports it.
  • Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are supported. Answers are plain JSON; there is no server-sent event stream and no session id.

Quick check from a terminal:

curl -s https://app.luminobot.com/api/v1/mcp/ \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

For client developers: sign-in is OAuth 2.1 with PKCE (S256). Discovery is at https://app.luminobot.com/.well-known/oauth-protected-resource and https://app.luminobot.com/.well-known/oauth-authorization-server, clients can register themselves at /oauth/register, and a request without a valid token gets 401 with a WWW-Authenticate header pointing to the metadata. Access tokens last one hour; refresh tokens 30 days and change on every use.

Create an agent token

  1. Open Settings → AI agents (MCP) and click Create agent token.
  2. Give it a Name you will recognise, such as "Claude Code on my laptop".
  3. Make your choices (see above). Under Limits you can also set requests per minute, messages sent per day and posts published per day.
  4. Click Create token.
  5. Copy the token (it starts with lb_pat_). It is shown only once. The page also shows the setup snippets for each client with your token already filled in.

Treat the token like a password. Agent tokens work only for AI assistants (MCP), not for the REST API.

Check that it works

Open the connection under Settings → AI agents (MCP) and click Test connection. Luminobot connects the way an assistant would and shows "Connection works." with the number of tools and the accounts in each workspace — or what is wrong.

Then ask your assistant something simple, such as "Which workspaces can you see?".

If something goes wrong

  • The assistant says it isn't allowed to do something. The connection's mode or access level doesn't allow it. In drafts-only mode, sends and scheduled posts become drafts; some actions aren't available at all. Change the settings on the connection's page under Safety.
  • "This connection covers 2 workspaces … Pass workspace". The assistant didn't say which workspace to use. Tell it, for example "in the Acme Coffee workspace".
  • 401 Unauthorized. The token was copied incompletely, has expired or the connection was disconnected. Create a new token, or sign in again.
  • 429 Too many requests. The connection hit its requests-per-minute limit. Wait a minute or raise the limit under Safety.

More in Troubleshooting.