Setup Guide

How to connect FluentCart MCP to Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and Codex CLI. I made it as painless as I possibly could.

This takes about 5 minutes. You'll generate a password in WordPress, paste a config snippet into your AI client, and you're done. I've made it as boring and straightforward as possible — no ceremony, no hoops.

Prerequisites

Install Node.js 22+

The MCP server needs Node.js 22 or higher. Check what you've got:

node --version

See v22.x.x or higher? Brilliant. Move on. If not, grab it from nodejs.org or use nvm:

nvm install 22
nvm use 22

Why 22?

I use native fetch and top-level await. These aren't optional — they're baked into how the server works. Node 20 and below won't cut it.

Generate a WordPress Application Password

Application Passwords have been built into WordPress since version 5.6. They let the MCP server talk to your site's REST API without you handing over your actual login password. Sensible, that.

Log in to your WordPress admin
Go to Users → Profile (or click your username in the top-right)
Scroll to the Application Passwords section
Type a name — FluentCart MCP works fine
Click Add New Application Password
Copy the password immediately

It looks something like: aBcD eFgH iJkL mNoP qRsT uVwX

WordPress Shows This Once

I mean it. WordPress shows the password exactly once. Close that page without copying it and you're generating a new one. Ask me how I know.

Which Account?

Use an Administrator account. The MCP server needs admin-level access to manage orders, products, and settings. A limited-permission user will get 403 errors on nearly everything, which rather defeats the purpose.

Grab Your Three Values

You need exactly these:

Value	Example
WordPress URL	`https://your-store.com`
Username	`admin`
Application Password	`aBcD eFgH iJkL mNoP qRsT uVwX`

The URL is the root of your WordPress site. No trailing slash. No /wp-admin/. Just the domain.

Configure Your AI Client

Pick your weapon. Each one takes about 60 seconds.

Claude Desktop

Anthropic's standalone app. The one with the nice icon.

Open the Config File

macOS: Claude menu → Settings → Developer → Edit Config
Windows: File → Settings → Developer → Edit Config

This opens claude_desktop_config.json. If you prefer to find it manually:

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

Paste This

Replace the placeholder values with your actual credentials:

{
  "mcpServers": {
    "fluentcart": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://your-store.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "aBcD eFgH iJkL mNoP qRsT uVwX"
      }
    }
  }
}

Already Have Other MCP Servers?

Don't replace the whole file. Add "fluentcart": {...} inside your existing mcpServers object. Comma after the previous entry. You know the drill.

Restart the App

Fully close and reopen Claude Desktop. Look for the hammer icon in the chat input — click it and you should see FluentCart tools listed.

No hammer? Check Settings → Developer for error messages.

Claude Code

The terminal-based one. My personal favourite, obviously.

One Command

claude mcp add fluentcart \
  -e FLUENTCART_URL=https://your-store.com \
  -e FLUENTCART_USERNAME=admin \
  -e FLUENTCART_APP_PASSWORD="aBcD eFgH iJkL mNoP qRsT uVwX" \
  -- npx -y fluentcart-mcp

That's it. Start a new session and you're connected.

Check It Works

In your next Claude Code session, try:

Show me the FluentCart dashboard stats

If you see store data, you're golden. You can also verify with:

claude mcp list

Cursor

The AI code editor. Good taste.

Open MCP Settings

Settings → Cursor Settings → MCP → Add new global MCP server

This opens the mcp.json config file.

Paste This

{
  "mcpServers": {
    "fluentcart": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://your-store.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "aBcD eFgH iJkL mNoP qRsT uVwX"
      }
    }
  }
}

Save.

Verify

Back in Settings → MCP, you should see fluentcart with a green dot. Red dot means something's wrong — click it for the error.

Open Cursor's AI chat (Cmd+L / Ctrl+L) and ask about your store.

VS Code with GitHub Copilot

MCP support lives in Copilot Chat's agent mode.

Create the Config

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "fluentcart": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://your-store.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "aBcD eFgH iJkL mNoP qRsT uVwX"
      }
    }
  }
}

Or if you prefer user-level settings (settings.json):

{
  "mcp": {
    "servers": {
      "fluentcart": {
        "command": "npx",
        "args": ["-y", "fluentcart-mcp"],
        "env": {
          "FLUENTCART_URL": "https://your-store.com",
          "FLUENTCART_USERNAME": "admin",
          "FLUENTCART_APP_PASSWORD": "aBcD eFgH iJkL mNoP qRsT uVwX"
        }
      }
    }
  }
}

Switch to Agent Mode

Open Copilot Chat and switch to Agent mode using the mode selector at the top. This is mandatory — regular Chat mode doesn't use MCP servers. Microsoft's design choice, not mine.

Windsurf

Codeium's editor. Supports MCP natively.

Open MCP Config

Command palette (Cmd+Shift+P / Ctrl+Shift+P) → search "Open MCP Config". This opens mcp_config.json.

Paste This

{
  "mcpServers": {
    "fluentcart": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://your-store.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "aBcD eFgH iJkL mNoP qRsT uVwX"
      }
    }
  }
}

Save. Windsurf picks up the change automatically.

Verify

Open Cascade and ask about your store. If you see FluentCart tools in the tool list, you're in.

OpenAI Codex CLI

Set Environment Variables

Add to your .bashrc, .zshrc, or wherever you keep these:

export FLUENTCART_URL="https://your-store.com"
export FLUENTCART_USERNAME="admin"
export FLUENTCART_APP_PASSWORD="aBcD eFgH iJkL mNoP qRsT uVwX"

Add to Codex Config

In ~/.codex/config.json:

{
  "mcpServers": {
    "fluentcart": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://your-store.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "aBcD eFgH iJkL mNoP qRsT uVwX"
      }
    }
  }
}

Run It

Start a Codex session and ask about your store. The server starts automatically.

Docker — Remote / VPS / ChatGPT

If you want a persistent MCP endpoint that remote clients (ChatGPT, custom agents, other machines) can reach — run the Docker image. No Node.js install needed.

Pull and run

docker run -d \
  -p 3000:3000 \
  -e FLUENTCART_URL=https://your-store.com \
  -e FLUENTCART_USERNAME=admin \
  -e FLUENTCART_APP_PASSWORD="aBcD eFgH iJkL mNoP qRsT uVwX" \
  -e FLUENTCART_MCP_API_KEY=pick-a-strong-secret \
  --name fluentcart-mcp \
  vcodesh/fluentcart-mcp

That's it. The image runs the HTTP transport on port 3000 automatically.

Verify

curl http://localhost:3000/health

Should return {"status":"ok"}. If it does, your MCP endpoint is live at http://localhost:3000/mcp.

Connect your AI client

Point any HTTP-capable MCP client at your endpoint. For ChatGPT, paste the URL into the MCP server configuration. For remote access, put it behind a reverse proxy or Cloudflare Tunnel — the Deployment Guide walks you through it.

Set FLUENTCART_MCP_API_KEY

The FLUENTCART_MCP_API_KEY protects the MCP endpoint with a bearer token. Without it, anyone who finds your URL gets full access to your store. I'm not your mum, but I am telling you to set it.

Alternative: Shared Config File

If you use multiple AI clients (or just hate repeating yourself), you can create one config file that the MCP server reads automatically. Then your AI client configs don't need any credentials at all.

macOS / Linux:

mkdir -p ~/.config/fluentcart-mcp

~/.config/fluentcart-mcp/config.json

{
  "url": "https://your-store.com",
  "username": "admin",
  "appPassword": "aBcD eFgH iJkL mNoP qRsT uVwX"
}

Windows:

%APPDATA%\fluentcart-mcp\config.json

{
  "url": "https://your-store.com",
  "username": "admin",
  "appPassword": "aBcD eFgH iJkL mNoP qRsT uVwX"
}

Then your AI client config simplifies to:

{
  "mcpServers": {
    "fluentcart": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"]
    }
  }
}

Priority

Environment variables beat the config file. If you set FLUENTCART_URL as an env var and also have url in the config file, the env var wins. I check env vars first — deliberately.

Interactive Setup Wizard

Don't fancy editing JSON files by hand? Fair enough. The setup wizard walks you through it:

npx fluentcart-mcp setup

It asks three questions — your WordPress URL, username, and Application Password — then tests the connection against your site before saving anything. If the credentials are wrong, it tells you why and offers to retry. If they work, it writes the config file automatically.

┌  fluentcart-mcp setup
│
◇  WordPress URL
│  https://your-store.com
│
◇  WordPress username
│  admin
│
◇  Application Password
│  ••••••••••••••••••••••••
│
◇  Connected to Your Store Name
│
◇  Config written to ~/.config/fluentcart-mcp/config.json
│
└  You're all set. Run fluentcart-mcp to start the server.

After that, your AI client configs don't need any credentials — the MCP server reads them from the config file. One wizard run, every client covered.

When to use the wizard

The wizard creates the same ~/.config/fluentcart-mcp/config.json file described above. The only difference is that it validates your credentials before saving, so you find out immediately if something's wrong — rather than discovering it mid-conversation when your AI tries to list orders and gets a 401 instead.

Multiple Stores

Managing more than one store? Create separate MCP server entries:

{
  "mcpServers": {
    "store-production": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://shop.example.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    },
    "store-staging": {
      "command": "npx",
      "args": ["-y", "fluentcart-mcp"],
      "env": {
        "FLUENTCART_URL": "https://staging.example.com",
        "FLUENTCART_USERNAME": "admin",
        "FLUENTCART_APP_PASSWORD": "yyyy yyyy yyyy yyyy"
      }
    }
  }
}

Just tell the AI which store you're talking about: "Check orders on production" or "Create a test product on staging." It's smart enough to figure out which connection to use.

Test the Connection

After all that, ask your AI:

"Get the FluentCart dashboard stats"

If you see store data — orders, revenue, customer count — you're done. Well played.

If you see errors, I've catalogued every failure mode on the Troubleshooting page.

Prerequisites

Install Node.js 22+

Generate a WordPress Application Password

Grab Your Three Values

Configure Your AI Client

Claude Desktop

Open the Config File

Paste This

Restart the App

Claude Code

One Command

Check It Works

Cursor

Open MCP Settings

Paste This

Verify

VS Code with GitHub Copilot

Create the Config

Switch to Agent Mode

Windsurf

Open MCP Config

Paste This

Verify

OpenAI Codex CLI

Set Environment Variables

Add to Codex Config

Run It

Docker — Remote / VPS / ChatGPT

Pull and run

Verify

Connect your AI client

Alternative: Shared Config File

Interactive Setup Wizard

Multiple Stores

Test the Connection

Next Steps

Usage & Examples

Tool Reference

On this page