MCP server

The endpoint and keys

The server speaks MCP over Streamable HTTP at /api/mcp:

• On Magpie Cloud: https://yourteam.magpiecrm.com/api/mcp, with your own workspace name in place of yourteam.
• Self-hosted: <your PUBLIC_URL>/api/mcp.

Create a key in Settings, then Connect AI apps. Name it after the app, such as "Claude Desktop (laptop)". The key starts vtl_mcp_ and is shown once; the setup snippets on that page already include it. Make one key per app so you can revoke one without touching the others. Every request sends it as Authorization: Bearer <key>.

MCP keys are separate from the sign-up API keys under Signup forms and API: neither works in the other's place.

Set up your AI app

The server is called magpiecrm. Replace the address and key with yours; Settings, then Connect AI apps shows these snippets with both filled in.

Claude Code, in a terminal:

claude mcp add --transport http magpiecrm https://yourteam.magpiecrm.com/api/mcp \
  --header "Authorization: Bearer <your MCP key>"

Claude Desktop: open Settings, then Developer, then Edit Config, add this and restart Claude Desktop. It needs Node.js for npx.

{
  "mcpServers": {
    "magpiecrm": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://yourteam.magpiecrm.com/api/mcp",
        "--header",
        "Authorization:${MCP_AUTH}"
      ],
      "env": {
        "MCP_AUTH": "Bearer <your MCP key>"
      }
    }
  }
}

Cursor:

{
  "mcpServers": {
    "magpiecrm": {
      "url": "https://yourteam.magpiecrm.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your MCP key>"
      }
    }
  }
}

Codex CLI: add this, then set MCP_KEY to your key in the shell Codex runs from.

[mcp_servers.magpiecrm]
url = "https://yourteam.magpiecrm.com/api/mcp"
bearer_token_env_var = "MCP_KEY"

OpenAI API, as a tool in a Responses API request:

tools: [{
  type: "mcp",
  server_label: "magpiecrm",
  server_url: "https://yourteam.magpiecrm.com/api/mcp",
  headers: { Authorization: "Bearer <your MCP key>" },
  require_approval: "always",
}]

Anything else that supports MCP over Streamable HTTP works the same way: the address plus the Authorization header. OpenAI connects from its own servers, so a self-hosted copy needs a public HTTPS address for it; on localhost, only apps on the same computer can connect.

Adding MagpieCRM as a connector in the ChatGPT app or on claude.ai isn't supported yet. Those need an OAuth sign-in flow that isn't built.

Read-only, destructive and paid tools

Every tool carries MCP annotations, which your AI app uses to decide when to ask you first:

• Read-only tools, such as getLists, change nothing.
• Destructive tools, such as deleteCampaign, remove or overwrite data.
• Open-world tools, searchCompanies and searchPeople, use prospect credits on every call, and their descriptions say so.

The tools

The design tools build emails and surveys block by block and save each change straight away, as a design you can open and edit in the app's builder. A sent campaign can't be changed: duplicate it first.

searchImages picks from a fixed set of curated stock images. The brand kit (name, logo, colours, font, tone of voice, website and footer address) can only be set through these tools or the copilot.

What it can't do

• Send or schedule a campaign. You do that in the app.
• Reveal a prospect's email.
• Save prospects to a list.

It can search prospects (using credits), build and edit campaign drafts and templates, manage lists, contacts and surveys, and check campaign stats.

The in-app copilot

The copilot in the app uses the same tools, plus editing the email, survey or persona you have open, and undoing its own changes. It runs on your own Anthropic or OpenAI API key, added under Settings, then Copilot (a self-hosted copy can also use ANTHROPIC_API_KEY or OPENAI_API_KEY). Usage is billed to the key's owner. You choose the model and effort in the chat.

Three permission modes decide what it asks before doing:

• Auto-approve safe edits (the default): reads and design edits run freely; destructive changes still ask.
• Always ask: approve every tool that changes something.
• Bypass: run everything without asking.

Each turn can take up to 40 tool steps. Chats are saved and can be deleted. The copilot has the same limits as the MCP server: it can't send, reveal or save prospects.