MCP Server - Connect MerchantFlow to Claude, Cursor, and Windsurf

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude, Cursor, and Windsurf securely read data from third-party services. When you connect MerchantFlow via MCP, your AI assistant can answer questions about your store using real data from your account - your P&L, product margins, ad spend, cohorts, and business valuation - without you having to copy and paste numbers from dashboards.

Why you would want it

Most merchants spend 30+ minutes a week clicking through dashboards to answer questions like "What's my blended MER?" or "Which products are losing me money after ad spend?" MCP lets you ask those questions in plain English and get a direct, data-backed answer in your favourite AI tool.

Real examples from our beta users:

• "Summarise this week's P&L with comparison to last week." - full weekly briefing in 15 seconds.
• "I'm thinking of launching a product at $49 with $12 COGS and $8 ad spend per unit. Is it viable?" - viability check with break-even ROAS and a green/amber/red verdict.
• "Run my business valuation and tell me what's dragging the multiple down." - full SDE valuation plus scorecard.

What it can do

MerchantFlow currently exposes:

• 64 read-only tools across financial, product, ads, customer, monitoring, valuation, Markets, inventory, order, store-audit, marketing, reports, COGS, tax, and search categories. Four depend on per-channel attribution, which is off by default, so a typical connection lists 60.
• 6 guided prompts for common workflows such as weekly briefings, profit-leak audits, product launch checks, month-end close, growth scans, and exit-readiness reviews
• 4 read-only resources that help compatible clients orient themselves to your store, integrations, North Star definitions, and the tool catalog
• An interactive profit-and-loss waterfall that renders inside the chat, in clients supporting MCP Apps (Claude web and desktop, ChatGPT, VS Code, Cursor). Other clients get the same figures as text.

A connected AI client can:

• Read your full P&L with comparisons
• Rank products by revenue, profit, margin, or units
• Simulate new product viability
• Report ad performance and blended MER across Meta, Google, Snapchat, and TikTok
• Break down profit by country with the Markets tools
• Analyse cohorts, LTV, and CAC payback
• Audit inventory, stock velocity, dead stock, and multi-location gaps
• Look up orders, fulfillment delays, and high-risk orders
• Audit your catalogue for image, SEO, collection, redirect, and page issues
• Pull abandoned-cart, win-back, and customer-tier marketing lists
• List and generate any saved or template report
• Read COGS entries, cost history, and coverage
• Run the same business valuation as the dashboard
• Flag anomalies and sync health issues
• List customers by lifetime value and open one customer's full history
• Report margin per discount code, so you can see which promotions paid for themselves
• Show per-country tax exposure against your configured tax rules

All tools are read-only - they never change your store data. Write tools (update COGS, create expenses, trigger syncs) are planned for a future release with explicit confirmation flows.

Some tools are only available when the matching feature is enabled for your store. The attribution tools (get_attribution_breakdown, get_unattributed_revenue, run_sales_by_channel_report) are hidden unless per-channel attribution is turned on, so always trust the live tool list your client shows over any static list.

Privacy and trust

• Every tool call is scoped to your store. Other stores' data is inaccessible even if someone guesses an ID.
• Customer PII (emails, phones, addresses) is redacted by default in responses.
• Every call is logged to an audit trail you can inspect.
• You can revoke any connected AI client from Settings > Developer > MCP (/dashboard/settings/developer/mcp) at any time.
• There is no write scope, so no connected client can change your MerchantFlow data or your store. Full detail: MCP security and data handling.
• MCP access is included on every paid plan. How far back you can query depends on the plan - see below.

Plan limits

MCP is included on every paid plan. What differs is how far back a query can reach and how many calls you get.

Every 14-day trial includes full Plus access, so trials get full history.

Asking for a period that reaches past your window is not an error. You get every day inside the window plus a note saying where the data stops and what plan would cover the rest, so the AI can tell you it answered on 90 days rather than silently reporting a partial figure as a full one.

Ask your AI client to "list MerchantFlow capabilities" and it will report your plan, your exact history window and your remaining call budget.

Connection details

• Server URL: https://merchantflow.ai/api/mcp
• Transport: Streamable HTTP (JSON-RPC 2.0 over POST). There is no SSE endpoint - do not append /sse or any other suffix.
• Protocol version: 2025-11-25, with backwards compatibility for older clients.
• Auth: an Authorization: Bearer header, from either OAuth or a personal access token.

If the endpoint returns a bare 404

Besides needing a paid plan, the MCP endpoint sits behind a platform switch (mcp_server_enabled) that MerchantFlow controls. It is on by default for every workspace, but while it is off -- globally during an incident, or for a specific workspace -- https://merchantflow.ai/api/mcp answers 404 with an empty body rather than an authorization error. That is deliberate: it keeps the server undiscoverable rather than advertising that it exists but is closed to you.

So a 404 on a valid, in-date credential is not a client misconfiguration. Confirm your subscription is active, then contact support -- retrying, reconnecting, or re-issuing a token will not change it.

Two ways to authenticate

• OAuth (default) - the standard flow for Claude, Claude Code, Cursor, Windsurf, and VS Code on a workstation. Click Allow access in your browser when the client connects. If you are signed out of MerchantFlow at that moment, you sign in first and land back on the authorization page automatically.
• Personal access tokens - long-lived bearer tokens for headless environments (VMs, SSH sessions, CI runners, dev containers) that cannot open a browser. Scoped to specific reads, with configurable expiry, and revocable from Settings > Developer > MCP (/dashboard/settings/developer/mcp).

If you installed MerchantFlow from the Shopify App Store

Your account was created by the install and has no web password, so the sign-in page that opens during OAuth can look like a dead end. It is not: choose Continue with Shopify, enter your store domain (your-store.myshopify.com, or just the store handle from admin.shopify.com/store/your-store), and approve the sign-in in Shopify. You land straight back on the authorization page.

This works while MerchantFlow is installed on that store. If you have uninstalled it, open MerchantFlow from your Shopify admin to reconnect first. You can also set a web password if you would rather sign in that way.

Next steps

• Connect Claude - 2-minute setup on claude.ai and Claude Desktop, most popular
• Connect Claude Code - one command in the terminal (claude mcp add)
• Connect Cursor - for developer-operators
• Connect Windsurf - alternative IDE
• Connect VS Code Copilot - if you live in VS Code
• Personal access tokens - headless setup for VMs, SSH, CI, and containers
• Tool reference - all 54 tools with parameters and scopes, plus the built-in prompts and resources
• 15 example prompts - copy-paste prompts to try right now
• Power up with the Skill file - download the optional AI skill file to dramatically improve answer quality

---

Last updated: September 4, 2026