MCP Integration

Use RocketSDR’s MCP gateway to let external agents and automations create campaigns, preview targeting, manage sales assets (products/personas), and read performance analytics.

Need a machine-readable reference? Download the LLM quick reference: mcp-llm.md.

Quickstart

  1. For Claude and ChatGPT connectors, use the MCP OAuth client setup shown below.
  2. For scripts and legacy clients, create an API key in Settings → Integrations → MCP API Keys.
  3. Verify access with list_products and list_personas.
  4. Use search_targeting to find supported values.
  5. Run preview_leads and iterate until the audience looks right.
  6. Optionally run preview_email with a sample lead to see what the first email will look like.
  7. Create the campaign with create_campaign (or draft first).

Connector Setup

  • Server URL: https://api.rocketsdr.ai/api/mcp
  • OAuth Client ID: rocketsdr
  • OAuth Client Secret: leave blank

CSV Campaigns (Upload + Launch)

MCP supports CSV campaigns in two ways: inline csv_content for small lists, or stateless pre-upload via get_csv_upload_url and csv_url.

  • Required for CSV: type = csv plus normal required campaign fields (name, product_id, persona_id).
  • Inline mode: csv_content (+ optional csv_filename).
  • Pre-upload mode: call get_csv_upload_url, upload CSV to returned uploadUrl, then pass returned gcsUrl as csv_url.
  • Pre-upload policy enforces .csv uploads with a hard max size of 2 MB.

Option A: One-Shot CSV Campaign

curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"create_campaign",
      "arguments":{
        "name":"CSV Outreach Batch 1",
        "type":"csv",
        "product_id":12,
        "persona_id":7,
        "csv_filename":"batch-1.csv",
        "csv_content":"contact name,email,company,title\nAda Lovelace,ada@example.com,Analytical Engine,Founder\nGrace Hopper,grace@example.com,Compilers Inc,VP Engineering"
      }
    }
  }'

Option B: Draft Then Finalize

Use this when you want to save progress first, then launch later. If CSV is uploaded at draft time, finalize can run without re-uploading.

# 1) Create draft with CSV
curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"create_campaign_draft",
      "arguments":{
        "name":"CSV Draft Campaign",
        "type":"csv",
        "csv_filename":"draft-leads.csv",
        "csv_content":"contact name,email,company\nLinus Torvalds,linus@example.com,Kernel Org"
      }
    }
  }'

# 2) Finalize draft (replace DRAFT_ID)
curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"finalize_campaign_draft",
      "arguments":{
        "campaign_id":"DRAFT_ID",
        "name":"CSV Draft Campaign",
        "type":"csv",
        "product_id":12,
        "persona_id":7
      }
    }
  }'

Option C: Stateless Pre-Upload (Recommended for Larger CSVs)

# 1) Get signed upload URL
curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{"name":"get_csv_upload_url","arguments":{"filename":"batch-1.csv"}}
  }'

# 2) Upload your CSV with multipart POST to uploadUrl from step 1
#    Include every key/value from formFields returned by step 1
curl -X POST "<uploadUrl>" \
  -F "<field1>=<value1>" \
  -F "<field2>=<value2>" \
  -F "file=@batch-1.csv;type=text/csv"

# 3) Create campaign using gcsUrl from step 1 as csv_url
curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"create_campaign",
      "arguments":{
        "name":"CSV Outreach Batch 1",
        "type":"csv",
        "product_id":12,
        "persona_id":7,
        "csv_url":"<gcsUrl>"
      }
    }
  }'

First Request (cURL)

curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_products","arguments":{}}}'

Authentication & Security

RocketSDR MCP supports both OAuth bearer tokens and API keys. OAuth is the recommended option for remote connectors such as Claude and ChatGPT; API keys are kept for direct programmatic access.

Authorization: Bearer YOUR_ACCESS_TOKEN

Legacy and script clients can still authenticate with:

X-API-Key: YOUR_API_KEY
  • Claude and ChatGPT connectors should use the OAuth client settings shown above.
  • Keys are shown only once when created. Store them securely.
  • Revoke keys immediately if they are leaked.
  • Do not embed keys in frontend code or public repos.
  • Rate limits apply: preview_leads max 20/day, campaign creation max 10/day.

The request examples below use API keys because they are easy to reproduce with cURL. OAuth clients should send the same JSON-RPC payloads with an Authorization: Bearer ... header instead.

Gateway & JSON-RPC

MCP is exposed through a single JSON-RPC 2.0 gateway:

POST /api/mcp

Standard JSON-RPC Envelope

{
  "jsonrpc": "2.0",
  "id": 123,
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": { }
  }
}
  • id can be any value you use to correlate responses.
  • Tool errors return isError: true in the tool result.
  • Numeric IDs should be sent as JSON numbers (not strings).

MCP Handshake (Optional)

If you are using an MCP-native client that expects the initialization lifecycle, call initialize first and then send the initialized notification. After that, use tools/list and tools/call.

curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"your-client","version":"0.1.0"}}}'
curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","method":"initialized"}'

Streamable HTTP (SSE)

The gateway supports Streamable HTTP for MCP-native clients. If you send Accept: text/event-stream, the response is returned as an SSE event. A GET request can also open an SSE stream for server-initiated messages (keep-alive only at the moment).

# POST with SSE response
curl -sS https://api.rocketsdr.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Optional GET stream (keep-alives only)
curl -N https://api.rocketsdr.ai/api/mcp \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "MCP-Protocol-Version: 2025-06-18"

If you receive an Mcp-Session-Id header from initialize, include it on subsequent requests. If you do not send a session id, requests still work.