Skip to main content

​
Overview

The Outbox AI MCP Server is a Model Context Protocol server that exposes your Outbox workspace as a set of tools any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) can call directly. Once connected, the model can list your agents, run tools, send messages, manage workflows, query CRM opportunities, fetch transcripts, and more — without leaving the chat.
The MCP server is brand-neutral. Whitelabel deployments can rename the server, tools, and responses without leaking the underlying provider’s identity.

​
How It Works

The server is a thin authenticated proxy over the Outbox HTTP API. Every MCP tool call translates into a single REST request scoped to your company.

Per-Operation Tools

A curated set of high-value tools (e.g. agents_list, contacts_create, workflows_run) is exposed by default for accurate model selection.

Generic run_operation

Power-user operations stay reachable via a single run_operation tool that accepts an operation name and arguments.

​
Connection

The server speaks streamable-http by default and binds to 127.0.0.1:9001/mcp. For most users, the hosted endpoint is at: 
https://api.getoutbox.ai/mcp

​
Authentication

Send these headers on every connection:
HeaderValue
AuthorizationBearer <your-api-key>
X-Company-IDYour company UUID
X-Agency-ID(optional) Agency UUID for agency-scoped access
You can generate API keys from Settings → Integrations in the dashboard.

​
Example: Claude Desktop

Add this to claude_desktop_config.json: 
{
  "mcpServers": {
    "outbox": {
      "url": "https://api.getoutbox.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Company-ID": "YOUR_COMPANY_ID"
      }
    }
  }
}

​
Example: Cursor / VS Code

{
  "mcp": {
    "servers": {
      "outbox": {
        "type": "http",
        "url": "https://api.getoutbox.ai/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY",
          "X-Company-ID": "YOUR_COMPANY_ID"
        }
      }
    }
  }
}

​
Available Tool Groups

GroupOperations
AgentsList, create, get, update, delete, plus tools and files
ContactsList, create, update, delete, bulk delete, import
ConversationsList, fetch by contact
MessagesSend SMS, send email
CallsTrigger an AI call
WorkflowsList, create, get, update, delete, manage enrollments
Email CampaignsManage campaigns and senders
CRMPipelines and opportunities
ToolsList, run, view configuration and logs
TranscriptsList, fetch, download
For the full list, call the list_operations tool from any MCP client once connected.

​
Self-Hosting

If you run your own backend, the server ships in api/mcp/company_server.py: 
python3 -m api.mcp.company_server

​
Environment Variables

VariableDefaultDescription
MCP_BACKEND_BASE_URLhttp://127.0.0.1:8000Outbox API base URL
MCP_BACKEND_AUTHORIZATION—Fallback Authorization header for stdio/internal use
MCP_COMPANY_ID—Company UUID forwarded as X-Company-ID
MCP_AGENCY_ID—Agency UUID for agency-scoped validation
MCP_TRANSPORTstreamable-httpFastMCP transport
MCP_HOST127.0.0.1HTTP bind host
MCP_PORT9001HTTP bind port
MCP_PATH/mcpHTTP mount path
MCP_SERVER_NAMEplatform-backendServer name advertised to clients
MCP_REQUEST_TIMEOUT_SECONDS45Per-request timeout
MCP_EXPOSE_ALL_OPERATIONS0Set to 1 to register one tool per operation
MCP_SESSION_FILE.platform/session.jsonPath to active-client session file

​
Best Practices

Generate a dedicated API key for each MCP integration. Rotate keys when devices change hands.
Leave MCP_EXPOSE_ALL_OPERATIONS off unless you specifically need every operation as its own tool — large tool lists hurt model selection accuracy.
For one-off operations the model can call run_operation with the operation name and JSON arguments instead of exposing every endpoint.