Outbound OS
Live demo Get setup help
Browse documentation

Set up the MCP server

Updated 24 October 2026 · For version 0.3.0 · Edit on GitHub

The MCP server lets Claude and other Model Context Protocol clients use your CRM through a fixed set of tools — listing leads, importing lists, building campaigns, reading analytics. It runs as a second container next to the app and is off until you start it. See every tool.

1. Add two tokens

Generate two random values and add them to .env:

Terminal
openssl rand -hex 32   # run twice
.env
MCP_SERVICE_TOKEN=<first value>
MCP_BEARER_TOKEN=<second value>
  • MCP_SERVICE_TOKEN lets the MCP server call the Outbound OS API. Both containers read it from the same .env.
  • MCP_BEARER_TOKEN is what AI clients present. It is also the password on the sign-in step when claude.ai connects, unless you set a separate OAUTH_PASSWORD.

2. Start the MCP server

Terminal
docker compose --profile mcp up -d

It listens on port 3010 (change it with OUTBOUNDOS_MCP_PORT). Check it is up with curl http://localhost:3010/healthz.

3. Give it an HTTPS address

Remote clients such as claude.ai need HTTPS. Add a second site to your reverse proxy, for example with Caddy:

Caddyfile
mcp.example.com {
  reverse_proxy localhost:3010
}

4a. Connect Claude Code

Terminal
claude mcp add --transport http outbound-os \
  https://mcp.example.com/mcp \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"

Then ask something like “list my newest leads” and approve the tool call.

4b. Connect claude.ai or the Claude apps

  1. In Claude, open Settings → Connectors and add a custom connector.
  2. Enter https://mcp.example.com/mcp as the URL and press Connect.
  3. A sign-in page from your server opens. Enter OAUTH_PASSWORD (or MCP_BEARER_TOKEN if you did not set one). Access lasts 30 days and refreshes automatically.

5. Decide what needs approval

Every tool acts with the MCP server’s service credential, so a connected client can do what an admin can through those tools. Most clients can ask before each call; keep that on for anything that changes state:

KindTools
Sends messagessend_whatsapp, send_email, start_campaign
Deletesdelete_lead, delete_campaign, bulk_lead_action
Controls sendingsystem_pause_resume, pause_campaign, lead_toggle_pause
Read onlylist_leads, get_lead, lead_timeline, list_messages, analytics and status tools

Keeping it safe

  • Only expose the MCP server over HTTPS, and only if you use a remote client.
  • Rotate MCP_BEARER_TOKEN if it leaks; restart the MCP container to apply it.
  • Results of each tool call go to the model you are using. Connect only clients whose data handling you accept for your leads.