> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendler.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect your AI assistant to your SendPilot workspace to work with campaigns, leads, inbox conversations, and lead sourcing. SendPilot's Model Context Protocol (MCP) server gives your assistant tools for your workspace. Read campaign results, add leads, manage lead status, prepare LinkedIn outreach, and source new leads without writing API requests. | Setting | Value | | - | - | | API-key server URL | `https://mcp.sendpilot.ai` | | Transport | Streamable HTTP | | Authentication | Shared workspace API key, or a workspace-bound Clerk OAuth connection | | Tools | 22 tools, filtered by your credential's permissions and workspace access | > [!NOTE] > > Previously connected to `https://docs.sendpilot.ai/mcp`? That is the documentation-search server. For workspace data, use SendPilot's client setup below: an API key for supported developer/desktop clients, or a specific OAuth connection URL for web assistants. For OAuth, use the **connection URL shown in Integrations → MCP**, not the generic API-key URL above. Each URL is bound to its creator, workspace, assistant and selected permissions. See [OAuth setup, consent and refresh](https://docs.sendler.ai/ai/mcp-oauth.md). New OAuth connections use `https://mcp.sendpilot.ai/connections/`. For development, use `https://mcp-dev.sendpilot.ai` for API keys and the development connection URL shown in the dashboard for OAuth. **Existing links keep working.** `/mcp`, `/mcp/`, and `/mcp/connections/` remain supported without HTTP redirects. The root API-key URL exposes the same tools as `/mcp`. Keep an existing OAuth connection's URL exactly as saved: its token audience stays bound to that stored URL, including `/mcp` for older connections. ## Access and billing MCP access follows the **workspace owner's** subscription and the credential's effective permissions. Check the dashboard for the workspace's current access. Trial sending restrictions still apply. If access needs activation, the dashboard shows the applicable subscription options. Members and admins should ask the billing owner to manage access. The locked state shows a focused upgrade/order summary instead of the client chooser and old session list. **Continue to Checkout** opens Stripe for a first purchase. An existing active or payment-pending subscription instead shows **Manage Subscription**, avoiding another checkout; owners can manage billing and cancel renewal there. Management remains visible after activation. **Manage existing access** reveals previous connections and shared API keys on request for recovery/revocation. Cancellation preserves paid coverage through its paid-through date. Failed renewal does not extend that date. Restoring access re-enables unrevoked connections. Direct REST keeps its own entitlement rules; check the interface you are using rather than treating API access as proof of MCP access. ## Connect your assistant For a configured Claude/ChatGPT web connection, follow the [OAuth flow](https://docs.sendler.ai/ai/mcp-clients.md#oauth-connections). The steps below cover clients using an API key. **1. Choose your assistant** Open **Integrations → MCP**. First-time onboarding shows chat apps and developer tools, including Claude Code, Cursor, VS Code, Codex CLI and OpenCode. Select a client to open its setup; every alternative stays visible. Returning users start from connection activity. See [all supported clients](https://docs.sendler.ai/ai/mcp-clients.md). **2. Create or reuse a workspace API key** Click **Create API Key** in the setup panel, then **Use Key for Setup**. Or choose **Use Saved Key** and enter the full value you saved previously. You do not need to open the key-management list to connect. MCP and the public API use the **same workspace keys**. **API Keys** opens their management view. During locked access, expand **Manage existing access** to reach it. Save new keys when shown; masked values cannot be recovered. Revoking a shared key affects every integration using it. **3. Add the server to your client** Follow the client-specific steps and click **Copy Configuration**. The copy includes your key; its on-screen preview hides it. Keep it private and out of version control. Keys are held only for that setup session and cleared when it is unmounted, including leaving the tab, switching identity/workspace, or refreshing. The examples below use placeholders. Replace them locally. Never put your key in the server URL or a chat message. **4. Verify the workspace** Ask: **“Use SendPilot to show my workspace, available permissions, and campaigns. Don't change anything.”** Your assistant should call `get_workspace`, then `list_campaigns`. Check that the workspace name is the one you intended to connect. ### Client configuration **Claude Desktop** Claude Desktop supports remote OAuth through your Claude account. Select **Claude Desktop** in SendPilot and follow the [OAuth instructions](https://docs.sendler.ai/ai/mcp-oauth.md). No local bridge or tunnel is required. **Claude Desktop (local bridge)** remains a separate optional API-key setup for existing local configurations. See [legacy bridge instructions](https://docs.sendler.ai/ai/mcp-clients.md#claude-desktop-local-bridge). **ChatGPT Desktop** Desktop versions with **Settings → MCP servers** share a local configuration with Codex and can supply an API-key header. Select **ChatGPT Desktop** in SendPilot and follow the [desktop setup instructions](https://docs.sendler.ai/ai/mcp-clients.md#chatgpt-desktop). This does not apply to ChatGPT on the web. **Claude & ChatGPT on web** When OAuth is enabled, select the web assistant in SendPilot, review the selected workspace and access level, and create a connection. Copy its URL and public client ID into the assistant's OAuth connector settings. Sign in to Clerk as the user who created the connection. Follow the [OAuth connection instructions](https://docs.sendler.ai/ai/mcp-clients.md#oauth-connections). If OAuth is not offered in your workspace, use a supported desktop/API-key client. Do not choose “No authentication” or put an API key in the URL or OAuth secret field. **Claude Code** Register the server in the terminal where you run Claude Code. Replace the placeholder with your key locally: ```bash theme={null} claude mcp add --transport http sendpilot https://mcp.sendpilot.ai \ --header 'X-API-Key: YOUR_SENDPILOT_API_KEY' ``` Run `claude mcp list` to check the connection. Update the configuration if you rotate the key. You can alternatively read the header value from an environment variable when running the registration command. **Cursor** Add this entry to your MCP configuration in Cursor. Replace `YOUR_SENDPILOT_API_KEY` locally and keep the configuration containing your key out of version control. ```json theme={null} { "mcpServers": { "sendpilot": { "url": "https://mcp.sendpilot.ai", "headers": { "X-API-Key": "YOUR_SENDPILOT_API_KEY" } } } } ``` Reload the MCP connection in Cursor's settings. **VS Code** Add `.vscode/mcp.json`. Replace the placeholder locally and keep this file private: ```json theme={null} { "servers": { "sendpilot": { "type": "http", "url": "https://mcp.sendpilot.ai", "headers": { "X-API-Key": "YOUR_SENDPILOT_API_KEY" } } } } ``` Start the server from the MCP configuration and use Copilot Chat in Agent mode. For a shareable configuration file, use VS Code's password input variables instead of a literal key. **Codex** Add this to `~/.codex/config.toml`, replacing the placeholder locally: ```toml theme={null} [mcp_servers.sendpilot] url = "https://mcp.sendpilot.ai" http_headers = { "X-API-Key" = "YOUR_SENDPILOT_API_KEY" } ``` Run `codex mcp list` to confirm registration. You can alternatively use `bearer_token_env_var = "SENDPILOT_API_KEY"` with that environment variable set, instead of storing the key in `http_headers`. **OpenCode** Add this server to `opencode.json`, replacing the placeholder locally. Keep a configuration containing your key out of version control: ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "sendpilot": { "type": "remote", "url": "https://mcp.sendpilot.ai", "enabled": true, "headers": { "X-API-Key": "YOUR_SENDPILOT_API_KEY" } } } } ``` Restart OpenCode after changing its configuration, then run `opencode mcp list`. OpenCode also supports `"X-API-Key": "{env:SENDPILOT_API_KEY}"` when you prefer to supply the key through its environment. **Other clients** Use a client that supports **Streamable HTTP with an authentication header**: ```text theme={null} URL: https://mcp.sendpilot.ai X-API-Key: YOUR_SENDPILOT_API_KEY ``` `Authorization: Bearer YOUR_SENDPILOT_API_KEY` is also accepted on this API-key endpoint. OAuth-only clients must use a configured workspace-bound connection URL instead of this setup. ## What you can do | Area | Examples | | - | - | | Workspace | Check access, credit balance, and sender quotas | | Campaigns | List campaigns, inspect results, pause or resume a paused campaign | | Leads | List and inspect leads, import profiles, update outcomes | | Inbox | Read conversations, prepare messages and connection requests | | Lead sourcing | Start LinkedIn extraction or database searches, then read progress and results | See the [tool reference](https://docs.sendler.ai/ai/mcp-tools.md) for all 22 tools and their arguments. Creating a campaign, editing its sequence, and managing webhooks are not MCP tools; use the dashboard or the relevant API where supported. ### Discover lead-search filters Call `get_lead_search_filters` before `start_lead_search`. Omit `filter` to page through the 90 supported filter schemas, or provide a filter name and `query` to search its complete value catalog: ```json theme={null} {"filter":"industries","query":"software","limit":25} ``` Follow `next_cursor` with the same filter/query for additional values. Job titles, technologies, industries, departments and SIC/NAICS catalogs are available; free-form fields are marked `free_form` rather than presenting a misleading empty list of allowed values. Discovery does not spend credits. Use the public `industries` field; SendPilot maps it to the provider's supported industry filter. `is_mapped_industries_strict=true` requests exact industry matching. Unsupported/removed filters are rejected before submission: correct them or ask the user, never silently remove a constraint and broaden the search. See [filter discovery](https://docs.sendler.ai/api-reference/endpoint/get-lead-filters.md). ### Use complete conversation IDs Pass the full `id` from `list_conversations` into `get_conversation_messages`. Provider IDs may exceed 128 characters; the tool accepts up to 2,048. Do not shorten, decode, or guess an ID. After updating an existing client, refresh its tool schemas if it still enforces the old limit. ### Choose read-only access when appropriate New dashboard OAuth connections preselect **Read and Write**. Select **Read Only** before creation for a read-only grant. Existing grants are not changed by this default; see [OAuth permission sets](https://docs.sendler.ai/ai/mcp-oauth.md#1-review-your-workspace-and-access). For API-key clients, use `https://mcp.sendpilot.ai/mcp/readonly` to expose only read tools. Toolset URLs also include `/mcp/account`, `/mcp/campaigns`, `/mcp/leads`, `/mcp/inbox`, `/mcp/senders`, and `/mcp/sourcing`. OAuth clients select Read Only during connection creation; do not append a toolset to an OAuth resource URL. Toolsets limit which tools that connection exposes. They do not change the underlying API key's permissions. `get_workspace` reports the key's current scopes and missing permissions; tools may also be unavailable because of the workspace's plan or a service setting. ## Approvals and writes Messages, connection requests, and campaign resumes require approval. Imports into campaigns that have already run also require review. Large sourcing requests require approval before spending credits. SendPilot currently uses a preview-and-confirmation-token flow (rather than relying on client-rendered approval forms). The first call returns: ```json theme={null} { "status": "confirmation_required", "summary": "Review the action before it runs.", "preview": {}, "confirmation_token": "TOKEN_FROM_SENDPILOT", "expires_at": "…" } ``` This is a preview, not a completed action. Review the sender, recipients, message, or estimated credits. Only after you approve should the assistant repeat the **same arguments** with `confirm: true` and the returned token. Approvals expire after ten minutes and are bound to the arguments and explicit idempotency key, if supplied. * **Draft imports:** `add_leads` can add up to 500 profiles to a draft or never-started campaign without an outreach approval. * **Previously started campaigns:** imports are limited to 50 profiles per approval. Running campaigns begin outreach; paused campaigns wait for resume. * **Lead status:** `DONE`, `UNSUBSCRIBED`, and `IRRELEVANT` stop further campaign outreach to that lead. Supplying `note` replaces existing notes. * **Trials:** LinkedIn sending tools are unavailable on trials by default. Read tools and eligible draft imports can still be used. ### Credits and limits Extraction costs **1 credit per lead**. Database searches reserve **2 credits per requested lead**, returning unused credits when completed. The preview shows the estimate and available balance when readable. By default, sourcing asks for approval above 100 estimated credits or when another unapproved spend would pass that day's 100-credit allowance. It also asks when the estimate exceeds 20% of the readable available balance. The MCP daily cap is **2,000 credits per credential** by default (API key or OAuth connection). Approval does not bypass available credits, the cap, sender quotas, or API limits. Workspace settings can change the cap and tool availability. Individual MCP extraction/search calls accept at most 2,000/1,000 leads respectively; REST has its own request limits. ### Retries without duplicate actions For tools that accept `idempotency_key`, reuse the same key for retries of the same operation. Identical calls without an explicit key are also deduplicated within the 24-hour window. Replayed results include `duplicate_suppressed: true`. To deliberately run a new operation, use a new key and obtain a new approval when required. A new approval token alone does not create a new operation. If a tool reports `DELIVERY_UNCONFIRMED`, `UPSTREAM_TIMEOUT`, or an uncertain idempotency outcome, check the conversation or job status before attempting another send or spend. ## Example prompts * **Campaign review:** “Show my campaigns and summarize replies. Don't make changes.” * **Draft import:** “Add these LinkedIn profiles to my draft campaign and report how many were added or skipped.” * **Prepare outreach:** “Draft a message for this lead and show the SendPilot approval preview. Wait for my approval.” * **Lead sourcing:** “Preview a database search for 100 sales directors in Sweden. Show the credit estimate before starting.” Profile fields and incoming messages come from other people. Your assistant should treat their content as data, not instructions to send messages or change your workspace. ## Use it in code Install `@modelcontextprotocol/client@2.1.0` and set `SENDPILOT_API_KEY` in your environment: ```typescript theme={null} import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client"; const apiKey = process.env.SENDPILOT_API_KEY; if (!apiKey) throw new Error("Set SENDPILOT_API_KEY"); const client = new Client({ name: "my-integration", version: "1.0.0" }); await client.connect(new StreamableHTTPClientTransport( new URL("https://mcp.sendpilot.ai"), { requestInit: { headers: { "X-API-Key": apiKey } } }, )); try { const result = await client.callTool({ name: "get_workspace", arguments: {} }); console.log(result.structuredContent); } finally { await client.close(); } ``` ## Troubleshooting > **I get a 401 or cannot connect** > > For API keys, check the server URL, authentication header, expiry and revocation. OAuth-only clients must use the exact generated connection URL and the selected assistant's public client ID; follow the [OAuth troubleshooting guide](https://docs.sendler.ai/ai/mcp-oauth.md#troubleshooting). > **A tool is missing** > > Check your toolset URL and call `get_workspace` to inspect permissions. Sending tools also depend on the workspace plan and service settings. Refresh the client connection after changing access. > **A call asks for confirmation but doesn't run** > > That is the approval step. The assistant must show the preview and wait for you. If approval expires or the arguments change, request a fresh preview. If a campaign changes state during an import, recheck it before approving another attempt. > **A retry says the operation is in progress or uncertain** > > A previous attempt may already have acted. Reuse its job ID to check progress, or inspect the inbox for a send. Do not use a new idempotency key merely to bypass the refusal. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.