MCP Integration

Plan Availability

MCP integration is available on Starter and Professional plans. Free plan users will receive an upgrade prompt when attempting to use MCP tools.

What is MCP?

The Model Context Protocol (MCP) lets AI assistants like Claude, Cursor, and other MCP-compatible clients manage your SubscribeFlow data directly through natural language. Instead of writing API calls manually, you can ask your AI assistant to create subscribers, send campaigns, manage tags, and more.

How it works

The MCP server runs locally on your machine as a subprocess of your AI assistant. It communicates with your assistant via stdin/stdout and makes API calls to the SubscribeFlow backend on your behalf.

sequenceDiagram
    participant User as You
    participant AI as Claude Desktop/Code
    participant MCP as MCP Server (local)
    participant API as api.subscribeflow.net

    User->>AI: "Create a subscriber for user@example.com"
    AI->>MCP: call_tool("create_subscriber", {email: "user@example.com"})
    MCP->>API: POST /api/v1/subscribers (X-API-Key: sf_live_...)
    API-->>MCP: 201 Created {id, email, ...}
    MCP-->>AI: "Subscriber created: user@example.com"
    AI-->>User: "Done! I created the subscriber user@example.com."

Key points:

The MCP server is a Python package you install locally (pip install subscribeflow[mcp])
No server hosting needed on your side — it runs as a local process
All data operations go through our REST API with your API key
Your API key never leaves your machine — it is only sent to api.subscribeflow.net via HTTPS
Tier verification happens on the first tool call to ensure your plan includes MCP access

Installation

Install the SubscribeFlow Python SDK with the MCP extra:

pip install "subscribeflow[mcp]"

Or with uv:

uv pip install "subscribeflow[mcp]"

Setup for Claude Desktop

Add the following to your claude_desktop_config.json:

macOSWindows

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

File location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "subscribeflow": {
      "command": "uvx",
      "args": ["--from", "subscribeflow[mcp]", "subscribeflow-mcp"],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_...",
        "SUBSCRIBEFLOW_BASE_URL": "https://api.subscribeflow.net"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration.

Setup for Claude Code

Add SubscribeFlow as an MCP server in your project:

claude mcp add subscribeflow \
  -e SUBSCRIBEFLOW_API_KEY=sf_live_... \
  -e SUBSCRIBEFLOW_BASE_URL=https://api.subscribeflow.net \
  -- uvx --from "subscribeflow[mcp]" subscribeflow-mcp

Available Tools

Subscribers

Tool	Description
`list_subscribers`	List subscribers with optional status/tag filters
`get_subscriber`	Get a subscriber by ID
`get_subscriber_by_email`	Look up a subscriber by email address
`create_subscriber`	Create a new subscriber
`get_or_create_subscriber`	Get existing or create new subscriber
`update_subscriber`	Update subscriber metadata or status
`delete_subscriber`	Delete a subscriber
`add_subscriber_tags`	Add tags to a subscriber
`remove_subscriber_tag`	Remove a tag from a subscriber
`generate_preference_token`	Generate a preference center token

Notes

Tool	Description
`create_note`	Add a note to a subscriber
`list_notes`	List notes for a subscriber
`get_note`	Get a specific note
`update_note`	Update a note
`delete_note`	Delete a note

Templates

Tool	Description
`list_templates`	List email templates
`get_template`	Get a template by slug
`create_template`	Create an MJML email template
`update_template`	Update a template
`delete_template`	Delete a template
`preview_template`	Preview a rendered template

Emails

Tool	Description
`send_email`	Send a transactional email using a template

Campaigns

Tool	Description
`list_campaigns`	List campaigns
`get_campaign`	Get campaign details
`create_campaign`	Create a new campaign
`update_campaign`	Update a draft campaign
`send_campaign`	Send a campaign to recipients
`cancel_campaign`	Cancel a sending campaign
`retry_campaign`	Retry failed campaign sends
`duplicate_campaign`	Duplicate an existing campaign
`count_campaign_recipients`	Count matching recipients for tag filters

Triggers

Tool	Description
`list_triggers`	List automated email triggers
`get_trigger`	Get trigger details
`create_trigger`	Create an event-based trigger
`update_trigger`	Update a trigger
`delete_trigger`	Delete a trigger

Webhooks

Tool	Description
`list_webhooks`	List webhook endpoints
`get_webhook`	Get webhook details
`create_webhook`	Create a webhook endpoint
`update_webhook`	Update a webhook
`delete_webhook`	Delete a webhook
`test_webhook`	Send a test event to a webhook
`regenerate_webhook_secret`	Regenerate webhook signing secret
`list_webhook_deliveries`	List deliveries for an endpoint
`get_webhook_delivery`	Get delivery details
`retry_webhook_delivery`	Retry a failed delivery
`get_webhook_stats`	Get delivery statistics for an endpoint
`list_all_webhook_deliveries`	List deliveries across all endpoints
`get_global_webhook_stats`	Get global delivery statistics
`list_webhook_event_types`	List available event types

Preference Center

Tool	Description
`get_preferences`	Get subscriber preferences (requires token)
`subscribe_to_tag`	Subscribe to a tag
`unsubscribe_from_tag`	Unsubscribe from a tag
`export_subscriber_data`	Export subscriber data (GDPR)
`delete_subscriber_account`	Delete subscriber account (GDPR)

Billing

Tool	Description
`get_subscription`	Get current plan and subscription details
`get_usage`	Get current usage counters and limits

Example Usage

Once configured, you can interact with SubscribeFlow through natural language:

"List all active subscribers tagged with 'newsletter'"
"Create a new subscriber with email user@example.com and tag them with 'product-updates'"
"Show me the campaign statistics for the Spring Campaign"
"Send a test event to webhook wh-uuid-1"
"How many emails have I sent this month?"

Troubleshooting

API key not set

Error: SUBSCRIBEFLOW_API_KEY environment variable is required.

Make sure your SUBSCRIBEFLOW_API_KEY is set in the MCP server configuration. The key must start with sf_live_ or sf_test_.

Free tier error

MCP integration is available on Starter and Professional plans.

MCP tools require a paid plan. Upgrade at your Billing dashboard.

Connection issues

If the MCP server fails to connect, verify:

Your API key is valid and not expired
The SUBSCRIBEFLOW_BASE_URL is correct (default: https://api.subscribeflow.net)
Your network allows outbound HTTPS connections to the API

Tool	Description
`list_tags`	List all tags
`get_tag`	Get a tag by ID
`get_tag_by_name`	Look up a tag by name
`create_tag`	Create a new tag
`get_or_create_tag`	Get existing or create new tag
`update_tag`	Update tag properties
`delete_tag`	Delete a tag