MCP Server - Outbox AI

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:

Header	Value
`Authorization`	`Bearer <your-api-key>`
`X-Company-ID`	Your 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

Group	Operations
Agents	List, create, get, update, delete, plus tools and files
Contacts	List, create, update, delete, bulk delete, import
Conversations	List, fetch by contact
Messages	Send SMS, send email
Calls	Trigger an AI call
Workflows	List, create, get, update, delete, manage enrollments
Email Campaigns	Manage campaigns and senders
CRM	Pipelines and opportunities
Tools	List, run, view configuration and logs
Transcripts	List, 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

Variable	Default	Description
`MCP_BACKEND_BASE_URL`	`http://127.0.0.1:8000`	Outbox 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_TRANSPORT`	`streamable-http`	FastMCP transport
`MCP_HOST`	`127.0.0.1`	HTTP bind host
`MCP_PORT`	`9001`	HTTP bind port
`MCP_PATH`	`/mcp`	HTTP mount path
`MCP_SERVER_NAME`	`platform-backend`	Server name advertised to clients
`MCP_REQUEST_TIMEOUT_SECONDS`	`45`	Per-request timeout
`MCP_EXPOSE_ALL_OPERATIONS`	`0`	Set to `1` to register one tool per operation
`MCP_SESSION_FILE`	`.platform/session.json`	Path to active-client session file

Best Practices

Scope API keys to the smallest needed surface

Generate a dedicated API key for each MCP integration. Rotate keys when devices change hands.

Prefer the curated tool list

Leave MCP_EXPOSE_ALL_OPERATIONS off unless you specifically need every operation as its own tool — large tool lists hurt model selection accuracy.

Use run_operation for ad-hoc calls

For one-off operations the model can call run_operation with the operation name and JSON arguments instead of exposing every endpoint.

​Overview

​How It Works

Per-Operation Tools

Generic run_operation

​Connection

​Authentication

​Example: Claude Desktop

​Example: Cursor / VS Code

​Available Tool Groups

​Self-Hosting

​Environment Variables

​Best Practices

Overview

How It Works

Connection

Authentication

Example: Claude Desktop

Example: Cursor / VS Code

Available Tool Groups

Self-Hosting

Environment Variables

Best Practices