Model Context Protocol (MCP)

The Flexprice Model Context Protocol (MCP) server provides a set of tools that AI agents can use to interact with the Flexprice API: customers, plans, subscriptions, invoices, payments, events, and more.

What is the Flexprice MCP server?

An MCP server that exposes your Flexprice API as MCP tools so AI assistants can call your API without reading REST docs.
Authenticated via API key (no OAuth). You provide the key in your MCP client config.
Works with any MCP client that supports stdio: Cursor, VS Code, Claude Desktop, Claude Code, Gemini, Windsurf, and others.

How you can connect: Flexprice currently supports two ways to run the MCP server. Pick what fits your workflow:

npx (recommended): One command, no install. Run npx -y @flexprice/mcp-server start with your API key and server URL. Ideal for Cursor, VS Code, Claude Code, Gemini, Windsurf, and most MCP clients.
Local or Docker: Clone the repo and run with Node, or use the official Docker image. Great for development, custom builds, or environments where you prefer not to use npx.

MCP server quick start

Cursor

One-click install

VS Code

One-click install

Claude Code

See instructions

Gemini

See instructions

Windsurf

See instructions

Other clients

See all options

Authenticating the MCP server

The MCP server uses your Flexprice API key only (no OAuth).

Where to get the key: From your Flexprice account (Dashboard or API keys settings).
Where to set it: In the MCP config as --api-key-auth YOUR_API_KEY (npx) or in the env object as API_KEY_APIKEYAUTH (local/Docker). Do not commit API keys; rotate if exposed.

Base URL / API URL (important): The MCP server’s --server-url (or equivalent) must use one of FlexPrice’s API base URLs. The two allowed URLs are:

US Region: https://us.api.flexprice.io/v1
India Region: https://api.cloud.flexprice.io/v1

MCP server security and credentials

Do not commit API keys. Keep your key only in local MCP config or environment variables.
Rotate keys if a key is ever committed or exposed.
We recommend enabling human confirmation for write or destructive operations in your MCP client.

We advise caution when giving LLMs write access to production data. Always review actions before execution. Use caution when using the Flexprice MCP with other servers to avoid prompt injection attacks.

Installing the Flexprice MCP server

Installing in Cursor

Cursor

Click to install the MCP server configuration for Cursor.

Manual installation:

Open Cursor → Settings → Cursor Settings and go to the MCP tab.
Click + Add new global MCP server (or open the MCP configuration file).
Add the following to your ~/.cursor/mcp.json file. Replace YOUR_API_KEY with your Flexprice API key. See Cursor MCP documentation.

{
  "mcpServers": {
    "flexprice": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}

Save and restart Cursor.

Installing in VS Code

VS Code

Click to install the MCP server configuration for VS Code.

Manual installation:

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run MCP: Add Server or MCP: Open User Configuration.
Add the following to your MCP config. Replace YOUR_API_KEY with your Flexprice API key. See VS Code MCP documentation.

{
  "servers": {
    "flexprice": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}

Save and restart VS Code.

Installing in Claude Code

Claude Code

See instructions below.

Manual installation:

Run the following command to add the Flexprice MCP server. Replace YOUR_API_KEY with your Flexprice API key.

claude mcp add Flexprice -- npx -y @flexprice/mcp-server start --server-url https://us.api.flexprice.io/v1 --api-key-auth YOUR_API_KEY

Enter Claude Code: claude
List MCP servers with /mcp to confirm the server is connected. See Claude Code MCP documentation.

Installing in Gemini

Gemini

See instructions below.

Manual installation:

Run the following command. Replace YOUR_API_KEY with your Flexprice API key.

gemini mcp add Flexprice -- npx -y @flexprice/mcp-server start --server-url https://us.api.flexprice.io/v1 --api-key-auth YOUR_API_KEY

Enter Gemini: gemini and use /mcp list to verify. See Gemini CLI for details.

Installing in Windsurf

Windsurf

See instructions below.

Manual installation:

Open Windsurf Settings → Cascade → Manage MCPs → View raw config.
Add the Flexprice server to the config (same JSON structure as Cursor). Replace YOUR_API_KEY with your Flexprice API key. See Windsurf MCP documentation.

Installing in other MCP clients

Other clients

See instructions below.

For Claude Desktop and other MCP clients, use the same npm package config. Example (Claude Desktop: add to your Claude Desktop config file, then quit and reopen):

{
  "mcpServers": {
    "flexprice": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}

Config file locations: Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json. Alternative: run from local repo (Node). If you cloned the Flexprice repo and run the server with node:

{
  "mcpServers": {
    "flexprice": {
      "command": "node",
      "args": ["/path/to/mcp-server/bin/mcp-server.js", "start"],
      "env": {
        "API_KEY_APIKEYAUTH": "your_api_key_here",
        "BASE_URL": "https://us.api.flexprice.io/v1"
      }
    }
  }
}

Alternative: Docker (stdio).

{
  "mcpServers": {
    "flexprice": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY_APIKEYAUTH",
        "-e",
        "BASE_URL",
        "flexprice-mcp"
      ],
      "env": {
        "API_KEY_APIKEYAUTH": "your_api_key_here",
        "BASE_URL": "https://us.api.flexprice.io/v1"
      }
    }
  }
}

Replace /path/to/mcp-server and env values as needed. Save the config and restart your client.

What can you ask the MCP server?

Once connected, you can ask your AI assistant to:

“List my customers” or “Get customer by id …”
“Create a subscription for customer … on plan …”
“Get plan by id …” or “List plans”
“Get usage for subscription …”

Which tools the MCP server exposes

The server exposes the Flexprice API as MCP tools (one tool per OpenAPI operation). We recommend enabling human confirmation of tools and exercising caution when using the Flexprice MCP with other servers to avoid prompt injection attacks.

Resource	Example tools
Customers	`get_customers`, `post_customers`, `get_customers_id`
Plans	`get_plans`, `get_plans_id`, `post_plans`
Subscriptions	`post_subscriptions`, `get_subscriptions_id`, `post_subscriptions_id_cancel`
Invoices	`get_invoices`, `get_invoices_id`, `post_invoices`
Payments	`get_payments`, `post_payments`
Events	`post_events`, `post_events_bulk`
Features	`get_features`, `post_features`
Prices	`get_prices`, `post_prices`
Wallets	`get_wallets_id`, `post_wallets_id_top_up`

For the full list, see your MCP client’s tool list after connecting or the API Reference.

Troubleshooting the MCP server

Symptom	Fix
Server does not appear	Save the MCP config and restart your client (Cursor, VS Code, Claude Desktop).
Invalid URL or 404	The server uses `BASE_URL` + path. Set base URL to `https://us.api.flexprice.io/v1` (include `/v1`, no trailing slash). For npx: use `--server-url https://us.api.flexprice.io/v1`. For local/Docker: set `BASE_URL` in `.env` or the MCP config `env` object.
API or connection errors	Verify your API key and base URL. Test with `curl -H "x-api-key: YOUR_KEY" https://us.api.flexprice.io/v1/customers`.
Rate limiting	Reduce request frequency or contact Flexprice support.
Port in use (local run)	Change the port in config or stop the process using it (e.g. `lsof -i :3000` then `kill -9 PID`).
Docker issues	Ensure env vars are passed into the container. Rebuild with `--no-cache` if the build fails.

API Reference: full list of Flexprice API operations (each maps to an MCP tool).

​What is the Flexprice MCP server?

​MCP server quick start

Cursor

VS Code

Claude Code

Gemini

Windsurf

Other clients

​Authenticating the MCP server

​MCP server security and credentials

​Installing the Flexprice MCP server

​Installing in Cursor

Cursor

​Installing in VS Code

VS Code

​Installing in Claude Code

Claude Code

​Installing in Gemini

Gemini

​Installing in Windsurf

Windsurf

​Installing in other MCP clients

Other clients

​What can you ask the MCP server?

​Which tools the MCP server exposes

​Troubleshooting the MCP server

​Related MCP and API references

What is the Flexprice MCP server?

MCP server quick start

Authenticating the MCP server

MCP server security and credentials

Installing the Flexprice MCP server

Installing in Cursor

Installing in VS Code

Installing in Claude Code

Installing in Gemini

Installing in Windsurf

Installing in other MCP clients

What can you ask the MCP server?

Which tools the MCP server exposes

Troubleshooting the MCP server

Related MCP and API references