> ## Documentation Index
> Fetch the complete documentation index at: https://www.foxreach.io/docs/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 to FoxReach.

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

## Prerequisites

* A FoxReach account with an active workspace
* 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 to FoxReach">
    Claude Desktop opens a browser window on FoxReach. Sign in the way you usually do (Google, an emailed sign-in link, or email and password) and click **Allow**. 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 to FoxReach in the browser window and click **Allow**. 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 FoxReach sign-in.

## Available Tools

FoxReach exposes 61 tools across eleven resource categories:

### Leads

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

### Campaigns

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

### Sequences

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

### Templates

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

### Email Accounts

| Tool | Read/Write | Description |
| - | - | - |
| `list_email_accounts` | Read | List connected email accounts |
| `get_email_account` | Read | Get an email account with warmup and health info |
| `create_email_account` | Write | Connect a new account via SMTP/IMAP app password |
| `update_email_account` | Write | Update display name, daily limit, or active status |
| `enable_warmup` | Write | Turn on warmup for an account |
| `disable_warmup` | Write | Turn off warmup for an account |
| `get_email_account_health` | Read | Get deliverability and warmup health metrics |
| `delete_email_account` | Write | Remove an account |

### Lead Finder

`search_people`, `search_companies`, and `count_lead_finder_results` take `filters` as a typed object with named keys (not a free-form JSON string), so an unknown key is rejected with a 400 naming it instead of being silently dropped. `get_lead_finder_filters` lists every valid key.

| Tool | Read/Write | Description |
| - | - | - |
| `get_lead_finder_filters` | Read | Get valid industries, company types, countries, and the full list of filter keys |
| `count_lead_finder_results` | Read | Count people matching a set of filters |
| `search_people` | Read | Search a licensed people database |
| `search_companies` | Read | Search the same database's company records |
| `reveal_leads` | Write | Reveal work emails for people from a search (spends credits) |
| `list_reveal_batches` | Read | List the workspace's reveal history for a month |
| `get_reveal_batch` | Read | Check the status of a reveal batch |
| `get_lead_finder_credits` | Read | Get the reveal credit balance and search budget usage |

### Tracking Domains

| Tool | Read/Write | Description |
| - | - | - |
| `list_tracking_domains` | Read | List the workspace's custom tracking domains |
| `add_tracking_domain` | Write | Register a custom tracking domain |
| `verify_tracking_domain` | Write | Re-check a tracking domain's provisioning status |
| `delete_tracking_domain` | Write | Remove a custom tracking domain |

### Warmup

| Tool | Read/Write | Description |
| - | - | - |
| `get_warmup_pool` | Read | List warmup-enabled accounts with health and pool activity |
| `get_warmup_stats` | Read | Aggregate warmup stats across the workspace's accounts |

### Managed Mailboxes

| Tool | Read/Write | Description |
| - | - | - |
| `check_domain_availability` | Read | Check if a domain is available to register, with price |
| `suggest_domains` | Read | Get available domain name alternatives with prices |
| `quote_managed_mailboxes` | Read | Price a set of domains and mailboxes |
| `list_managed_mailboxes` | Read | List the workspace's managed mailboxes |
| `list_mailbox_orders` | Read | List the workspace's managed mailbox orders |

### Analytics

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

### Inbox

| Tool | Read/Write | Description |
| - | - | - |
| `list_inbox_threads` | Read | List inbound reply threads with category filtering and search |
| `get_inbox_conversation` | Read | Get the full conversation for an inbox thread |
| `send_inbox_reply` | Write | Send a reply to an inbox thread |
| `get_inbox_stats` | Read | 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 OAuth, with FoxReach itself as the identity provider. Your MCP client opens a browser window on FoxReach's sign-in page; use Google, an emailed sign-in link, or your email and password, then approve the connection. 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](/docs/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>

### Connect with an API key

Hosts that cannot complete a browser-based sign-in flow (the Claude Messages API MCP connector, headless agents, CI, and most server-to-server integrations) can authenticate with a FoxReach API key instead of OAuth. Create one in **Settings > API Keys**, then send it as either:

```
Authorization: Bearer otr_...
```

or, for hosts that only let you configure arbitrary headers:

```
X-API-Key: otr_...
```

Tool calls made with an API key run against that key's own workspace, and its scopes and plan limits apply exactly as they do for the [REST API](/docs/authentication). A `read`-only key can still list tools, but gets a clear error back from any write tool.

## 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 sign in again.

**"No FoxReach account found" error**
The account you signed in with has no FoxReach workspace. 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](/docs/errors) as the API (e.g., 404 for not found, 409 for duplicate email).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.