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

# MCP Server

> Connect Claude, Cursor, and other AI agents to FoxReach using the Model Context Protocol (MCP).

## Overview

FoxReach provides a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI agents manage your leads, campaigns, templates, and email accounts through natural language. No local installation required — just point your AI client at `https://api.foxreach.io/mcp` and sign in with Google.

**Supported clients:** Claude Desktop, Cursor, Claude Code, and any MCP-compatible client.

## Prerequisites

* A FoxReach account with an active workspace (sign-in email must match your Google account)
* A compatible MCP client installed

## Setup

### Claude Desktop

<Steps>
  <Step title="Open Claude Desktop settings">
    Go to **Settings > Connectors > Add custom connector**.
  </Step>

  <Step title="Add the FoxReach MCP server">
    Enter `FoxReach` as the name and the following remote MCP server URL:

    ```
    https://api.foxreach.io/mcp
    ```
  </Step>

  <Step title="Sign in with Google">
    Claude Desktop opens a browser window for Google sign-in. Use the same email as your FoxReach account. Once authorized, the MCP tools icon appears in the chat input area, confirming the connection.
  </Step>
</Steps>

### Cursor

<Steps>
  <Step title="Open Cursor settings">
    Go to **Settings > MCP** in Cursor.
  </Step>

  <Step title="Add a new MCP server">
    Click **Add new MCP server** and configure it with the following JSON:

    ```json theme={null}
    {
      "foxreach": {
        "url": "https://api.foxreach.io/mcp"
      }
    }
    ```
  </Step>

  <Step title="Verify connection">
    Cursor prompts you to authenticate — sign in with the Google account matching your FoxReach email. The server should show a green status indicator once connected.
  </Step>
</Steps>

### Claude Code

Run this command in your terminal:

```bash theme={null}
claude mcp add foxreach \
  --transport http \
  "https://api.foxreach.io/mcp"
```

Then run `/mcp` inside Claude Code to complete the Google sign-in.

## Available Tools

FoxReach exposes 36 tools across seven resource categories:

### Leads

| Tool                | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `list_leads`        | List leads with optional search and status filtering            |
| `get_lead`          | Get a single lead by ID                                         |
| `create_lead`       | Create a new lead (deduplicates by email)                       |
| `import_csv_leads`  | Import leads from a CSV uploaded in the FoxReach chat           |
| `update_lead`       | Update an existing lead's fields                                |
| `delete_lead`       | Delete a lead by ID                                             |
| `get_lead_activity` | Get a lead's full activity timeline — sends, replies, campaigns |

### Campaigns

| Tool                           | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `list_campaigns`               | List campaigns with optional status filtering  |
| `get_campaign`                 | Get a campaign by ID, including sequence steps |
| `create_campaign`              | Create a new campaign in draft status          |
| `update_campaign`              | Update an existing campaign                    |
| `delete_campaign`              | Delete a campaign (must be in draft status)    |
| `start_campaign`               | Start a draft campaign — begins sending        |
| `pause_campaign`               | Pause an active campaign                       |
| `resume_campaign`              | Resume a paused campaign                       |
| `assign_leads_to_campaign`     | Add leads to a campaign                        |
| `remove_lead_from_campaign`    | Remove a lead from a campaign                  |
| `assign_accounts_to_campaign`  | Assign sending email accounts to a campaign    |
| `remove_account_from_campaign` | Remove a sending account from a campaign       |

### Sequences

| Tool              | Description                               |
| ----------------- | ----------------------------------------- |
| `list_sequences`  | List a campaign's sequence steps in order |
| `create_sequence` | Add a sequence step (email) to a campaign |
| `update_sequence` | Update an existing sequence step          |
| `delete_sequence` | Delete a sequence step from a campaign    |

### Templates

| Tool              | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `list_templates`  | List email templates with optional category filtering |
| `get_template`    | Get a single template by ID                           |
| `create_template` | Create a new email template                           |
| `update_template` | Update an existing template's fields                  |
| `delete_template` | Delete a template by ID                               |

### Email Accounts

| Tool                  | Description                                      |
| --------------------- | ------------------------------------------------ |
| `list_email_accounts` | List connected email accounts                    |
| `get_email_account`   | Get an email account with warmup and health info |

### Analytics

| Tool                     | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| `get_workspace_overview` | Workspace-level stats — accounts, campaigns, leads, sends, reply rate |
| `get_campaign_stats`     | Sent, delivered, bounced, replied, and opened counts for a campaign   |

### Inbox

| Tool                     | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| `list_inbox_threads`     | List inbound reply threads with category filtering and search |
| `get_inbox_conversation` | Get the full conversation for an inbox thread                 |
| `send_inbox_reply`       | Send a reply to an inbox thread                               |
| `get_inbox_stats`        | Inbox totals, unread count, and category breakdown            |

## Example Prompts

Once connected, you can use natural language to interact with FoxReach:

* **"List all my active campaigns"** — calls `list_campaigns` with status filter
* **"Create a lead for [john@acme.com](mailto:john@acme.com) at Acme Inc"** — calls `create_lead`
* **"Pause the campaign named Q1 Outreach"** — calls `list_campaigns` to find it, then `pause_campaign`
* **"Show me all email templates"** — calls `list_templates`
* **"Draft a cold outreach template and save it"** — AI writes the copy, then calls `create_template`

## Authentication

The MCP server authenticates with Google OAuth. Your MCP client opens a browser window for Google sign-in — use the same email address as your FoxReach account. Behind the scenes, FoxReach mints a short-lived session API key scoped to your personal workspace, so tool calls carry the same permissions and plan limits as the [REST API](/authentication).

All communication is encrypted via HTTPS.

<Tip>
  Session keys created by MCP appear in **Settings > API Keys** as `MCP Session (...)` entries. They expire automatically after 2 hours and expired entries are cleaned up on the next connection.
</Tip>

## Troubleshooting

**Tools not appearing in Claude Desktop**
Make sure the URL in your config is exactly `https://api.foxreach.io/mcp`. Restart Claude Desktop after making changes.

**"401 Unauthorized" error**
Your session has expired or the tokens are stale. Clear the server's authentication in your MCP client and reconnect to re-run the Google sign-in.

**"No FoxReach account found" error**
The Google account you signed in with doesn't match any FoxReach account email. Sign in with the email you use for FoxReach, or create an account first.

**Connection drops or timeouts**
Streamable HTTP connections are long-lived. Some network environments or proxies may drop idle connections. Your MCP client will automatically reconnect.

**Tool calls returning errors**
The MCP tools call the FoxReach REST API under the hood. Check the error message — it follows the same [error format](/errors) as the API (e.g., 404 for not found, 409 for duplicate email).