MCP Server Integration¶

Subscribe Flow provides an MCP server (Model Context Protocol) that enables LLM agents like Claude to interact directly with the Subscribe Flow API.

What is MCP?¶

The Model Context Protocol (MCP) is a protocol developed by Anthropic that securely connects LLMs with external tools. The Subscribe Flow MCP server exposes 66 tools for managing subscribers, tags, templates, emails, campaigns, triggers, webhooks, billing, the preference center, and platform administration.

All MCP tools are organization-scoped via the API key. The MCP server automatically filters all operations to the organization associated with the configured API key.

Installation¶

1

pip install "subscribeflow[mcp]"

Configuration¶

Claude Desktop¶

Path to configuration file: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 1: With uv (Recommended)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "mcpServers": {
    "subscribeflow": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/subscribe-flow/sdk/python",
        "run", "subscribeflow-mcp"
      ],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Option 2: With full path

After installing with pip install "subscribeflow[mcp]":

1
2
3

# Find the path
which subscribeflow-mcp
# Example: /Users/username/.local/bin/subscribeflow-mcp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "mcpServers": {
    "subscribeflow": {
      "command": "/Users/username/.local/bin/subscribeflow-mcp",
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Option 3: With Python module

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "subscribeflow": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "subscribeflow.mcp.server"],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

The production URL https://api.subscribeflow.net is set as the default.

Claude Code¶

Add the configuration to ~/.claude.json or ~/.claude/settings.json.

With uv (Recommended):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "mcpServers": {
    "subscribeflow": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/subscribe-flow/sdk/python",
        "run", "subscribeflow-mcp"
      ],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Local Development¶

For a local Subscribe Flow instance, add SUBSCRIBEFLOW_BASE_URL:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "mcpServers": {
    "subscribeflow": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/subscribe-flow/sdk/python",
        "run", "subscribeflow-mcp"
      ],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_dev_xxx",
        "SUBSCRIBEFLOW_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Remote Access (claude.ai Custom Connector)¶

Besides the local stdio process above, the SDK's MCP server also runs as a Streamable HTTP server reachable at https://api.subscribeflow.net/mcp — no local process and no local Python install needed. subscribeflow-api exposes /mcp as a thin, unauthenticated reverse proxy onto an internal mcp Fly process group running the SDK's own HTTP server; the Authorization header configured in claude.ai is a regular SubscribeFlow API key, validated the same way every other API call is. See docs/superpowers/specs/2026-09-22-tf-903-remote-mcp-connector-design.md for the full design.

Setup¶

1. Create a dedicated API key for MCP use (Admin Dashboard or just api-key). Leave allowed_ips empty — the connector's requests arrive from Anthropic's infrastructure via an internal Fly hop, not from a fixed, allowlistable address.
2. In claude.ai: Organization Settings → Connectors → Add → Custom Connector.
   • URL: https://api.subscribeflow.net/mcp
   • Static header: Authorization: Bearer <the key from step 1>
3. Connect and run one read-only tool (e.g. "list our tags") to confirm the end-to-end path works.

Differences from the local (stdio) setup¶

• Per-request auth, not per-process. The local server reads SUBSCRIBEFLOW_API_KEY once at startup; the remote server reads the Authorization header on every request, so it could in principle serve multiple keys — Phase 1 just configures one, shared across the organization's claude.ai members.
• Rate-limited per client IP at the /mcp proxy (120 requests/minute by default, mcp_proxy_rate_limit setting) — the only guard available before the credential itself is checked, since the proxy performs no auth of its own.
• Tool listing requires a valid key too. Unlike the tier check (which only gates tools/call), tools/list over HTTP validates the API key before returning the catalog — a bogus Authorization header gets a JSON-RPC error, not the tool list.
• The mcp Fly process group is pinned to exactly one machine; expect a brief interruption during a deploy.

See docs/deployment/fly-io-setup.md for the process group's operational details and docs/superpowers/plans/2026-09-22-tf-903-remote-mcp-connector.md (Task 8) for the full rollout checklist.

Use Cases¶

1. Newsletter Management¶

1
2
3
4
5
6

You: "Add max@example.com to the Weekly Newsletter"

Claude: I'll create the subscriber and assign the tag.
        [create_subscriber, get_or_create_tag]

        Done! max@example.com has been added to "Weekly Newsletter".

2. Subscriber Analysis¶

1
2
3
4
5
6
7
8
9

You: "How many active subscribers do we have in the 'product-updates' tag?"

Claude: [get_tag_by_name, list_subscribers]

        The "product-updates" tag has 1,247 active subscribers.
        The 5 most recent sign-ups:
        - anna@example.com (2 hours ago)
        - tom@example.com (5 hours ago)
        ...

3. Bulk Tag Creation¶

1
2
3
4
5
6
7
8

You: "Create tags for our product categories: Electronics, Fashion, Home"

Claude: [create_tag x3]

        All three tags have been created:
        - Electronics (ID: abc123)
        - Fashion (ID: def456)
        - Home (ID: ghi789)

4. Preference Center Link¶

1
2
3
4
5
6
7

You: "Generate a preference center link for support@customer.com"

Claude: [get_subscriber_by_email, generate_preference_token]

        Here is the link:
        https://subscribeflow.net/preferences?token=eyJ...
        (Valid for 7 days)

5. Billing & Usage Check¶

1
2
3
4
5
6
7
8

You: "How many subscribers can we still add this month?"

Claude: [get_subscription, get_usage]

        Your plan: Starter
        - Subscribers: 3,421 / 5,000 (1,579 remaining)
        - Emails: 12,340 / 10,000 this month
        - Webhooks: 2 / 3 configured

6. Subscriber Search¶

1
2
3
4
5
6
7
8

You: "Find all subscribers with @company.com email addresses"

Claude: [list_subscribers]

        Found: 23 subscribers with @company.com:
        - admin@company.com (active, Tags: newsletter, updates)
        - sales@company.com (active, Tags: newsletter)
        ...

7. Tag Statistics¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

You: "Show me an overview of all tags with subscriber counts"

Claude: [list_tags]

        Tag overview:
        | Tag              | Subscribers | Public |
        |------------------|-------------|--------|
        | Newsletter       | 5,234       | Yes    |
        | Product Updates  | 1,247       | Yes    |
        | Internal         | 42          | No     |

8. Webhook Monitoring¶

1
2
3
4
5
6
7
8

You: "Test all configured webhooks"

Claude: [list_webhooks, test_webhook x3]

        Webhook test results:
        - Main Webhook (https://app.com/hook): OK (127ms)
        - Backup (https://backup.com/hook): OK (234ms)
        - Analytics (https://analytics.com/hook): ERROR (Timeout)

9. Subscriber Migration¶

1
2
3
4
5
6
7
8

You: "Move all subscribers from the 'old-newsletter' tag to 'new-newsletter'"

Claude: [get_tag_by_name x2, list_subscribers, update_subscriber x...]

        Migration completed:
        - 847 subscribers moved
        - 3 already in the new tag (skipped)
        - 0 errors

10. Automating Welcome Emails¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

You: "Set up an automatic welcome email that is sent when new subscribers
     sign up"

Claude: [list_templates, create_trigger]

        Trigger created:
        - Event: subscriber.created
        - Template: "Welcome Email" (welcome-email)
        - Status: active

        From now on, every new subscriber will automatically receive the
        welcome email.

11. Sending a Newsletter Campaign¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

You: "Create a campaign for the February newsletter and send it to all
     newsletter subscribers"

Claude: [list_tags, list_templates, create_campaign, count_campaign_recipients,
         send_campaign]

        Campaign "February Newsletter 2026" created and started:
        - Template: Monthly Newsletter
        - Recipients: 3,421 (Tag: newsletter)
        - Status: sending

        Sending is running in the background. You can check the progress with
        "Show the status of the February campaign".

12. Previewing a Template¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

You: "Show me a preview of the welcome email with company data for Acme AG"

Claude: [get_template_by_slug, preview_template]

        Here is the preview for "Welcome Email":
        - Subject: "Welcome to Acme AG!"
        - HTML preview generated

        The template variables have been populated:
        - {{company}} -> "Acme AG"
        - {{year}} -> "2026"

13. Analyzing Webhook Deliveries¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

You: "Show me the delivery statistics for our main webhook"

Claude: [list_webhooks, get_webhook_delivery_stats]

        Webhook "Main Production" (https://app.com/hook):
        - Total: 12,847 deliveries
        - Successful: 12,691 (98.8%)
        - Failed: 156 (1.2%)
        - Average response time: 142ms

        Would you like me to show the failed deliveries?

14. GDPR Data Export¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

You: "Export all stored data for privacy@customer.com"

Claude: [get_subscriber_by_email, generate_preference_token,
         preference_center_get_info, preference_center_export_data]

        Data export for privacy@customer.com created:
        - Subscriber profile: active since 2025-03-15
        - Subscribed tags: Newsletter, Product Updates
        - Metadata: source=website, plan=premium
        - Audit log: 23 entries
        - Exported on: 2026-02-15, 10:30 AM

15. Checking Campaign Recipients in Advance¶

1
2
3
4
5
6
7
8
9

You: "How many subscribers would receive a campaign targeting 'premium'
     but not 'churned'?"

Claude: [count_campaign_recipients]

        Recipient check:
        - Include: Tag "premium"
        - Exclude: Tag "churned"
        - Result: 847 active subscribers would receive the campaign

Available Tools (66 total)¶

Subscriber Tools (8)¶

Tag Tools (7)¶

Template Tools (7)¶

Email Tools (1)¶

Campaign Tools (7)¶

Trigger Tools (5)¶

Billing Tools (2)¶

Webhook Tools (5 basic + 9 extended)¶

Preference Center Tools (5)¶

Platform Admin Tools (10)¶

Security¶

API Key Scopes¶

For the MCP server, we recommend an API key with the required scopes:

1
2
3
4
5
6
7

subscribers:read
subscribers:write
tags:read
tags:write
templates:read
templates:write
billing:read

billing:read is not optional despite the short list above: every tool call runs a tier check (GET /api/v1/billing/subscription) before dispatching, regardless of which tool was actually invoked, so a key without it fails on the very first call with "Could not verify your plan" — not just on billing tools.

Optional (only if needed):

1
2
3

webhooks:manage
campaigns:manage
triggers:manage

Destructive Operations¶

The tools delete_subscriber, delete_tag, delete_webhook, delete_template, delete_trigger, and cancel_campaign are marked as destructive. Claude will ask for confirmation before executing them.

Troubleshooting¶

MCP Server Does Not Start¶

1. Check whether the package is installed:

   Bash
   1	pip show subscribeflow

2. Test the server manually:

   Bash
   1	SUBSCRIBEFLOW_API_KEY=sf_live_xxx subscribeflow-mcp

"Unauthorized" Error¶

• Check the API key: It should start with sf_live_ or sf_test_
• Verify the key permissions in the admin dashboard

"Plan Required" Error (403)¶

• MCP access requires at least the Starter plan
• Check your current plan: GET /api/v1/billing/subscription
• Upgrade via the admin dashboard or POST /api/v1/billing/checkout

Tools Are Not Displayed¶

• Restart Claude Desktop/Code
• Check the configuration file for JSON syntax errors
• Check the logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Further Reading¶

• SDK Setup Guide - Python & TypeScript SDK
• API Reference - REST API documentation
• Authentication Guide - API key management