> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getoutbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, Cursor, and other MCP clients to your Outbox AI workspace

## Overview

The Outbox AI **MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io) 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.

<Note>
  The MCP server is brand-neutral. Whitelabel deployments can rename the server,
  tools, and responses without leaking the underlying provider's identity.
</Note>

## 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.

<CardGroup cols={2}>
  <Card title="Per-Operation Tools" icon="wrench">
    A curated set of high-value tools (e.g. `agents_list`, `contacts_create`,
    `workflows_run`) is exposed by default for accurate model selection.
  </Card>

  <Card title="Generic run_operation" icon="bolt">
    Power-user operations stay reachable via a single `run_operation` tool that
    accepts an operation name and arguments.
  </Card>
</CardGroup>

## 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`:

```json theme={null}
{
  "mcpServers": {
    "outbox": {
      "url": "https://api.getoutbox.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Company-ID": "YOUR_COMPANY_ID"
      }
    }
  }
}
```

### Example: Cursor / VS Code

```json theme={null}
{
  "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`:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Scope API keys to the smallest needed surface" icon="shield-halved">
    Generate a dedicated API key for each MCP integration. Rotate keys when
    devices change hands.
  </Accordion>

  <Accordion title="Prefer the curated tool list" icon="list-check">
    Leave `MCP_EXPOSE_ALL_OPERATIONS` off unless you specifically need every
    operation as its own tool — large tool lists hurt model selection accuracy.
  </Accordion>

  <Accordion title="Use run_operation for ad-hoc calls" icon="terminal">
    For one-off operations the model can call `run_operation` with the
    operation name and JSON arguments instead of exposing every endpoint.
  </Accordion>
</AccordionGroup>