Connect Claude to MoltFlow via MCP

Claude gains full WhatsApp API access through MoltFlow's native MCP endpoint. One config entry gives Claude 26 tools across sessions, messages, leads, groups, outreach, and usage. Setup takes 2 minutes — no npm packages, no local servers, no Node.js required.

New: OAuth 2.1 authentication — Just add the MCP URL. No API key needed. Claude will prompt you to sign in via your browser on first use.

Unlike Custom GPT Actions (which require manual OpenAPI imports), MCP (Model Context Protocol) provides Claude with native tool discovery, streaming responses, and stateful context. Claude doesn't just call your API — it understands your WhatsApp automation platform as if it were built-in functionality.

MoltFlow hosts the MCP endpoint natively at https://apiv2.waiflow.app/mcp using Streamable HTTP transport. This guide covers three connection methods: Claude Desktop, Claude.ai web, and Claude Code. Choose the method that fits your workflow.

What You'll Need

Before starting, make sure you have:

• A MoltFlow account — Available on all plans (Free, Starter, Pro, Business). Sign up here if you don't have an account yet.
• One of these clients:
  • Claude Desktop app — Download from claude.ai/download (macOS, Windows, Linux)
  • Claude.ai web account — No installation needed
  • Claude Code CLI — For developers using Claude in the terminal

No API key, Node.js, or npm packages required. MoltFlow hosts the MCP endpoint natively with OAuth 2.1 — all clients connect via Streamable HTTP and authenticate via browser sign-in.

Why Claude + MoltFlow?

MCP turns Claude into a first-class WhatsApp automation client. Instead of copying data between dashboards, Claude accesses your MoltFlow account directly:

• Native tool execution — Claude calls MoltFlow APIs as if they were built-in commands
• Streaming responses — See session status, message counts, and lead details in real-time as Claude fetches them
• Context-aware workflows — Claude remembers your sessions, groups, and campaigns across your conversation
• Multi-step operations — Complex workflows like "create group, add contacts, send bulk message" handled in one request

Example use cases:

• Ask Claude "How many messages did I send this week?" and get usage analytics instantly
• Say "Send a follow-up to all leads from the NYC Events group" and Claude executes the full workflow
• Request "Show me sessions that need QR code renewal" and Claude filters by status automatically
• Command "Create a bulk send to my Newsletter group with [message]" and Claude confirms before executing

Step 1: Connect Claude Desktop (OAuth — Recommended)

Claude Desktop supports remote MCP servers via Streamable HTTP with OAuth 2.1. Just add the URL — no API key needed.

Locate your config file:

The Claude Desktop config file location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Create or edit the config file:

If the file doesn't exist, create it. If it exists, add the moltflow server to the mcpServers object.

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "moltflow": {
      "url": "https://apiv2.waiflow.app/mcp"
    }
  }
}

That's the entire config. No command, no args, no env, no API key — just a URL. Claude Desktop connects directly to MoltFlow's hosted endpoint over Streamable HTTP with automatic OAuth authentication.

Important for existing configs:

If your claude_desktop_config.json already has other MCP servers, just add moltflow to the mcpServers object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    },
    "moltflow": {
      "url": "https://apiv2.waiflow.app/mcp"
    }
  }
}

Restart Claude Desktop and connect:

After saving the config file:

1. Quit Claude Desktop completely (not just close the window)
2. Reopen Claude Desktop
3. Claude will prompt you that MoltFlow needs authentication
4. Your browser opens to the MoltFlow sign-in page
5. Sign in (or create a free account) and approve the connection
6. You're redirected back — Claude is now connected with full tool access

Look for a hammer icon in the chat input area. Hover over it to see moltflow in the connected servers list.

If you don't see the hammer icon, check the Claude Desktop logs for errors. Common issues: invalid JSON syntax or wrong config file path.

Step 2: Connect via Claude.ai Web

Claude.ai web users can connect to MoltFlow directly — no installation needed.

Configure MCP in Claude.ai:

1. Log in to Claude.ai
2. Click your profile icon in the bottom-left
3. Select Settings
4. Navigate to Integrations tab
5. Find MCP Servers section
6. Click "Add Server"

Enter connection details:

• Server Name: MoltFlow
• URL: https://apiv2.waiflow.app/mcp

1. Click Save

Claude.ai will discover OAuth automatically. On first use, you'll be prompted to sign in via your browser and approve the connection.

How it works:

MoltFlow hosts a native MCP endpoint at https://apiv2.waiflow.app/mcp using the Streamable HTTP transport. When you send commands from Claude.ai, requests go directly to MoltFlow's servers, which execute the API calls and return responses to Claude. OAuth 2.1 with PKCE handles authentication securely.

Advantages:

• No local software installation required
• No API key to manage — OAuth handles everything
• Works on any device with web browser access
• No Node.js or npm dependencies
• Tools always up to date (no manual package updates)

Security note:

The endpoint uses HTTPS with OAuth 2.1 (PKCE). Rate limits apply per your plan tier.

Step 3: Connect Claude Code

Claude Code connects to MoltFlow's native MCP endpoint with a single command:

claude mcp add moltflow --transport http --url https://apiv2.waiflow.app/mcp

No API key needed. This registers MoltFlow globally — all 26 tools are available in every Claude Code session. On first use, Claude Code will open your browser to sign in and approve the connection.

Using MCP tools conversationally:

Once connected, use MCP tools naturally:

"List my WhatsApp sessions"
"Send a message to +1-555-0123 saying hello"
"Show me new leads from this week"

Claude Code will execute the appropriate MCP tool calls automatically.

Step 4: Test MCP Tools with Sample Commands

Now that you've connected Claude to MoltFlow, let's test the integration.

Open a chat and try these commands:

1. List sessions:

"List my WhatsApp sessions"

Expected response: A formatted markdown table showing your sessions with columns for Name, Status (working/stopped/qr_code), Phone Number, and Session ID.

If you have no sessions, Claude will tell you how to create one.

2. Check usage:

"What's my current message usage?"

Expected response: Current billing period stats — messages sent, messages remaining, plan limits, and reset date. This confirms Claude can read your account data.

3. View leads:

"Show me new leads from this week"

Expected response: A list of leads captured in the last 7 days with status "new". Claude will format the results with contact name, phone, lead score, source group, and capture date.

4. Send a test message:

"Send a message to +1-555-0123 saying Hello from Claude via MCP!"

Replace +1-555-0123 with your own phone number. Claude will ask you to select a session if you have multiple, then send the message.

Check your phone — you should receive the message within seconds.

5. List available groups:

"What WhatsApp groups can I monitor for leads?"

Expected response: A list of groups from your connected sessions with group name, participant count, and whether they're already being monitored.

What to look for:

• Responses should be formatted in markdown (tables, bold text, lists) — not raw JSON
• Tool execution should happen automatically — Claude chooses the right MCP tool without you specifying it
• Claude should ask clarifying questions if needed (e.g., "Which session do you want to use?")
• Error messages should be actionable (e.g., "Session xyz-123 is stopped. Start it first.")

Test complex workflows:

Try multi-step commands:

"Create a custom group called 'Test Group', add +1-555-0001 and +1-555-0002 to it, then send them a bulk message saying 'Testing bulk send'"

Claude will execute multiple MCP tools in sequence:

1. moltflow_create_custom_group — Creates the group
2. moltflow_add_custom_group_members — Adds the contacts
3. moltflow_create_bulk_send — Sends the message

This demonstrates the power of MCP — Claude orchestrates multi-step workflows from a single request.

Step 5: Explore Available Tools and Customization

The MoltFlow MCP server provides 26 tools across 6 domains.

Sessions (5 tools)

Messages (3 tools)

Groups (7 tools)

Leads (2 tools)

Outreach (4 tools)

Usage (2 tools)

Response formats:

All tools support two response formats:

• markdown (default) — Human-readable formatted output with tables, lists, and bold text. Best for conversational use in Claude.
• json — Raw JSON response from the MoltFlow API. Best for programmatic processing or when you need exact field values.

To request JSON format, ask explicitly:

"List my sessions in JSON format"

Pagination:

List tools support limit and offset parameters for paginating through large result sets:

"Show me the first 10 leads"          -> limit: 10, offset: 0
"Show me the next 10 leads"           -> limit: 10, offset: 10
"Show me leads 21-30"                 -> limit: 10, offset: 20

When more results are available, Claude will indicate how to fetch the next page.

Step 6: Alternative — Manual API Key Setup

If your MCP client doesn't support OAuth, you can authenticate with an API key instead.

Create an API key:

1. Log in to MoltFlow Dashboard
2. Navigate to Sessions in the left sidebar
3. Click the API Keys tab
4. Click "Create API Key"
5. Name it Claude MCP Server and select Full Access scope preset
6. Click Create and copy the key immediately — it's shown only once

Claude Desktop with API key:

{
  "mcpServers": {
    "moltflow": {
      "url": "https://apiv2.waiflow.app/mcp",
      "headers": {
        "X-API-Key": "mf_your_api_key_here"
      }
    }
  }
}

Claude Code with API key:

claude mcp add moltflow --transport http --url https://apiv2.waiflow.app/mcp --header "X-API-Key: mf_your_api_key_here"

Replace mf_your_api_key_here with your actual key.

Connecting Any MCP-Compatible Client

Any client that supports MCP Streamable HTTP transport can connect to MoltFlow's native endpoint:

• Endpoint: https://apiv2.waiflow.app/mcp
• Protocol: MCP Streamable HTTP (2025-03-26)
• Auth: OAuth 2.1 (recommended) or X-API-Key header
• OAuth Discovery: https://apiv2.waiflow.app/.well-known/oauth-authorization-server
• Content-Type: application/json
• Accept: application/json, text/event-stream

No local servers, no npm packages, no Node.js required. The endpoint handles CORS, rate limiting, and HTTPS automatically. OAuth-capable clients just need the URL — authentication is handled via browser sign-in.

For detailed setup instructions and to see all available tools, visit the MCP setup page in your MoltFlow dashboard.

Troubleshooting

"401 Unauthorized" on Every Tool Call

Cause: OAuth token expired or API key is invalid.

Fix (OAuth): Remove and re-add the MoltFlow server in your Claude settings. On next use, you'll be prompted to sign in again via browser.

Fix (API key): Verify your API key is still active at Sessions > API Keys in the dashboard. Generate a new key if needed and update your config.

Tools Not Appearing in Claude Desktop

Cause: Claude Desktop doesn't see the MCP server.

Possible issues:

1. Config file is not valid JSON (trailing commas, missing quotes)
2. Config file is in the wrong location for your OS
3. Claude Desktop wasn't fully restarted

Fix:

1. Validate JSON: Use jsonlint.com to check syntax
2. Verify file location (see Step 2 for OS-specific paths)
3. Restart Claude Desktop: Quit completely (not just close window), then reopen
4. Check Claude Desktop logs for MCP server errors

OAuth Sign-In Not Opening

Cause: Your MCP client may not support OAuth 2.1, or a popup blocker is preventing the browser from opening.

Fix:

1. Check that your MCP client supports OAuth 2.1 with PKCE (Claude Desktop, Claude Code, and Claude.ai all do)
2. Disable popup blockers for molt.waiflow.app
3. If OAuth doesn't work, use the manual API key method instead

"403 Forbidden -- insufficient scope"

Cause: Your API key doesn't have the required scope for the tool you're trying to use.

Fix:

1. Create a new API key with the required scopes for the tools you need
2. Update your config with the new key
3. Restart Claude Desktop

"429 Rate Limited"

Cause: Too many requests in a short time.

Fix:

Wait for the retry period. Rate limits by plan:

• Free: 10 requests/min
• Starter: 60 requests/min
• Pro: 300 requests/min
• Business: 1,000 requests/min

For higher limits, upgrade your plan.

Session Stuck in "starting" State

Cause: The WAHA engine needs time to initialize.

Fix:

Wait 10-15 seconds, then ask Claude "What's the status of session [ID]?" to check progress. If it stays "starting" for more than 30 seconds, restart the session from the MoltFlow dashboard.

QR Code Expired

Cause: QR codes expire after approximately 60 seconds.

Fix:

Ask Claude "Get a fresh QR code for session [ID]" to generate a new one.

What's Next

Now that you've connected Claude to MoltFlow, explore these related integrations:

• Connect ChatGPT to MoltFlow via Custom GPT Actions — Give ChatGPT Plus full WhatsApp automation access with OpenAPI spec import
• Connect OpenClaw Bot to MoltFlow — Native AI integration for automatic WhatsApp replies
• Build a WhatsApp Support Bot — Combine AI with knowledge base for 24/7 customer service
• Connect MoltFlow to n8n — Integrate WhatsApp with 500+ apps via no-code workflows

Claude + MoltFlow via MCP turns natural language into WhatsApp automation. Use it for ad-hoc operations, team collaboration, or as a conversational alternative to the dashboard.

Ready to build more integrations? Check out MoltFlow's full REST API documentation for advanced workflows.

Need help? Contact support via the dashboard chat or email us at [email protected]. We typically respond within 2-4 hours.