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

# Connect AI Assistants (MCP)

> Use Claude, Cursor, VS Code and other AI assistants to find, send and track your CardClan cards through the Model Context Protocol.

CardClan has a built-in [MCP](https://modelcontextprotocol.io) server. Connect it to your AI assistant and you can manage cards in plain language:

> "Send the Holiday Thanks card to everyone in this list tomorrow at 9am, then tell me who opened it on Friday."

Your assistant works with your CardClan account, workspaces and plan limits, the same as when you use the app.

## What you need

* A CardClan account
* Your CardClan **API key**, found in **Settings → AI Assistants (MCP)**. This is the same key used for integrations like Pabbly Connect.
* An AI assistant that supports remote MCP servers, such as Claude Code, Claude Desktop, Cursor or VS Code

<Info>
  **Server URL:** `https://app.cardclan.io/api/mcp`

  **Transport:** Streamable HTTP · **Auth header:** `Authorization: Bearer YOUR_API_KEY`
</Info>

## Setup

<Steps>
  <Step title="Get your API key">
    In CardClan, open **Settings → AI Assistants (MCP)**. Click **Generate API key** if you don't have one yet, then copy it.
  </Step>

  <Step title="Add CardClan to your assistant">
    Choose your client below, or copy the ready-made snippet from the same settings page. The snippet there already includes your key.
  </Step>

  <Step title="Try it">
    Ask something like *"What CardClan cards do I have?"* Your assistant will call CardClan and answer.
  </Step>
</Steps>

<Tabs>
  <Tab title="Claude Code">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add --transport http cardclan https://app.cardclan.io/api/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    Start `claude` and run `/mcp` to confirm **cardclan** is connected.
  </Tab>

  <Tab title="Claude Desktop">
    Open **Settings → Developer → Edit Config** and add CardClan to `claude_desktop_config.json`, then restart Claude Desktop. Requires [Node.js](https://nodejs.org).

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "cardclan": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://app.cardclan.io/api/mcp", "--header", "Authorization:${CARDCLAN_AUTH}"],
          "env": { "CARDCLAN_AUTH": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

    ```json mcp.json theme={null}
    {
      "mcpServers": {
        "cardclan": {
          "url": "https://app.cardclan.io/api/mcp",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your workspace, or run **MCP: Add Server** from the command palette:

    ```json .vscode/mcp.json theme={null}
    {
      "servers": {
        "cardclan": {
          "type": "http",
          "url": "https://app.cardclan.io/api/mcp",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Any client that supports remote MCP servers over **Streamable HTTP** with a custom header will work:

    * **URL:** `https://app.cardclan.io/api/mcp`
    * **Header:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`)
  </Tab>
</Tabs>

<Note>
  ChatGPT connectors and claude.ai web connectors currently require OAuth sign-in, which the CardClan MCP server doesn't support yet. Use one of the clients above in the meantime.
</Note>

## What you can ask

<AccordionGroup>
  <Accordion title="Find and inspect cards" icon="magnifying-glass">
    * "List my cards in the Holidays folder"
    * "What merge tags does the Welcome card need?"
    * "Give me the share link for the Thank You card"
  </Accordion>

  <Accordion title="Send or schedule cards" icon="paper-plane">
    * "Send the Welcome card to [jane@acme.com](mailto:jane@acme.com) (company: Acme) now"
    * "Schedule the Holiday card for these 25 people on Dec 20 at 9am New York time"
    * "Also send last week's card to Sam"

    Your assistant first runs a **preview**: it checks every email address, makes sure each merge tag has a value, skips people who unsubscribed or already got the card, and shows how many plan recipients the send will use. It should ask you before anything is emailed.
  </Accordion>

  <Accordion title="Track delivery and engagement" icon="chart-line">
    * "Who opened the Holiday card?"
    * "Did any sends fail? Retry them"
    * "Cancel the scheduled send to [bob@acme.com](mailto:bob@acme.com)"
    * "How did my cards perform in the last 30 days?"
  </Accordion>

  <Accordion title="Organize" icon="folder">
    * "Create a folder called Q4 Clients and move these three cards into it"
    * "Rename the Holidays folder to Holidays 2026"
  </Accordion>
</AccordionGroup>

## Available tools

| Tool | What it does | Changes data |
| - | - | - |
| `whoami` | Your account and the workspaces you can access | No |
| `list_workspaces` | Workspaces with your role in each | No |
| `list_email_accounts` | Connected sender email accounts | No |
| `get_usage` | Remaining plan limits (recipients, cards, AI credits) | No |
| `list_cards` | Cards in a workspace, filterable by folder, status or title | No |
| `get_card` | Merge tags, subject line, sender, share link, delivery stats | No |
| `get_card_link` | Generic share link, or a personalized tracked link for one person (uses 1 plan recipient, no email sent) | Yes |
| `list_folders` / `create_folder` / `rename_folder` / `delete_folder` | Manage folders. Deleting a folder keeps its cards. | Yes, except list |
| `move_cards_to_folder` | Move cards into or out of a folder | Yes |
| `list_recipients` | Recipients with delivery status and whether they opened the email or viewed the card | No |
| `preview_send` | Dry run of a send: validation, sender, subject, schedule, quota impact | No |
| `send_card` | Email a card to up to 100 recipients per call, now or scheduled. Works on new and already-sent cards. | **Yes, sends email** |
| `cancel_scheduled_recipient` | Cancel a scheduled send. The recipient is returned to your plan. | Yes |
| `retry_recipient` | Re-send to a recipient whose delivery failed | **Yes, sends email** |
| `get_card_analytics` | Opens, views, reactions, comments and downloads for a card | No |
| `get_workspace_engagement` | Workspace engagement and most engaged contacts | No |

## Safety and limits

<Warning>
  Your API key gives full access to your CardClan account, including sending email. Keep it private. Don't commit it to code repositories or paste it into shared documents.
</Warning>

* **You stay in control.** Tools that change data or send email are marked as such, and most assistants ask for your approval before running them.
* **Plan limits apply.** Every recipient counts against your plan's recipient limit, exactly like sending from the app. A send that would go over your limit is refused.
* **Workspace access.** The assistant can only see workspaces you own or are an active member of.
* **Activity log.** Every action taken with your key appears under **Settings → AI Assistants (MCP) → Recent activity** for 90 days.
* **Rate limit.** 120 requests per minute per account.
* **Video cards** are still sent from the CardClan app.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401: Missing or invalid CardClan API key">
    Check that the header is exactly `Authorization: Bearer YOUR_API_KEY`, with no extra spaces or quotes. You can copy the full snippet from **Settings → AI Assistants (MCP)**.
  </Accordion>

  <Accordion title="Multiple workspaces available; pass workspaceId">
    Your account has more than one workspace. Tell the assistant which one to use, for example *"use my Marketing workspace"*.
  </Accordion>

  <Accordion title="Missing merge tag values">
    The card has merge tags without a fallback, such as `company`. Give the assistant a value for each recipient, or add a fallback to the merge tag in the card editor.
  </Accordion>

  <Accordion title="Not enough recipients left on the plan">
    The send needs more recipients than your plan has remaining. Send to fewer people or upgrade your plan in **Settings → Billing**.
  </Accordion>
</AccordionGroup>

Need help? Contact [support@cardclan.io](mailto:support@cardclan.io).


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