MCP Server - FlexPrice

The FlexPrice MCP server exposes the FlexPrice API as tools for AI assistants. Manage customers, plans, subscriptions, invoices, and events directly from Claude, Cursor, VS Code, or any MCP-compatible client.

Prerequisites

Node.js

Version 20 or higher

npm

Or yarn/pnpm/bun

API Key

From FlexPrice dashboard

Quick Start

Run the MCP server with one command:

npx @flexprice/mcp-server start \
  --server-url https://us.api.flexprice.io/v1 \
  --api-key-auth YOUR_API_KEY

Replace YOUR_API_KEY with your FlexPrice API key. Next: Add to your MCP client.

Installation Methods

npm package (Recommended)
Local repository
Docker

Install globally or run directly with npx:

# Install globally
npm install -g @flexprice/mcp-server

# Run directly with npx (no install)
npx @flexprice/mcp-server start \
  --server-url https://us.api.flexprice.io/v1 \
  --api-key-auth YOUR_API_KEY

Clone and run from source:

Clone repository

Clone the FlexPrice repository and navigate to the MCP server directory:

git clone https://github.com/flexprice/flexprice
cd flexprice/api/mcp

Install dependencies

npm install

Configure environment

Create a .env file:

BASE_URL=https://us.api.flexprice.io/v1
API_KEY_APIKEYAUTH=your_api_key_here

Build and start

npm run build
npm start

Build and run with Docker:

# Build image
docker build -t flexprice-mcp .

# Run with stdio
docker run -i \
  -e API_KEY_APIKEYAUTH=your_api_key_here \
  -e BASE_URL=https://us.api.flexprice.io/v1 \
  flexprice-mcp node bin/mcp-server.js start

The base URL must include /v1 with no trailing slash: https://us.api.flexprice.io/v1

Add to Your MCP Client

Configure the FlexPrice MCP server in your AI assistant or editor.

Cursor

Open Cursor Settings

Go to Cursor → Settings → Cursor Settings and click the MCP tab

Add MCP server configuration

Add this JSON configuration:

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

Verify connection

Open the MCP panel in Cursor to confirm the server is connected and list available tools

VS Code

Open MCP configuration

Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and run:

MCP: Open User Configuration, or
MCP: Add Server

Add server configuration

Add this configuration:

{
  "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"
      ]
    }
  }
}

Claude Code

Add the server via the CLI:

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

Then run claude and use /mcp to confirm connection.

Claude Desktop

Locate configuration file

Open the Claude Desktop config file:

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

Add server configuration

Add this configuration:

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

Restart Claude Desktop

Quit and reopen Claude Desktop to load the server

Available Tools

The MCP server exposes FlexPrice API operations as tools. Only operations with certain OpenAPI tags are included (e.g., Customers, Invoices, Events, Plans, Subscriptions). Common tools include:

Customers: createCustomer, listCustomers, getCustomer, updateCustomer
Events: ingestEvent, listRawEvents
Invoices: listInvoices, getInvoice, createInvoice
Plans: listPlans, getPlan, createPlan
Subscriptions: createSubscription, listSubscriptions, cancelSubscription

For the complete list, check your MCP client’s tool list after connecting or review the filtered OpenAPI spec (docs/swagger/swagger-3-0-mcp.json).

Dynamic Mode (Progressive Discovery)

For large tool sets, dynamic mode reduces context size by exposing meta-tools for on-demand discovery:

list_tools – List available tools with descriptions
describe_tool – Get input schema for specific tools
execute_tool – Run a tool by name with parameters

Enable dynamic mode by adding --mode dynamic:

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

Dynamic mode is recommended for servers with many tools to improve token efficiency and tool selection.

Scopes (Optional)

Limit tools by scope for read-only or restricted access:

npx @flexprice/mcp-server start \
  --server-url https://us.api.flexprice.io/v1 \
  --api-key-auth YOUR_API_KEY \
  --scope read

Use read for read-only operations when the server defines scope-based restrictions.

Example Usage

Once connected, ask your AI assistant to perform FlexPrice operations:

Create a new customer with email john@example.com and name "John Doe"

Alternative Configurations

Local Repository (Node)

For running from a cloned repo:

{
  "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"
      }
    }
  }
}

Docker

For Docker-based 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"
      }
    }
  }
}

Troubleshooting

Invalid URL or request errors

Ensure BASE_URL or --server-url is set to https://us.api.flexprice.io/v1 (no trailing slash)
Verify the base URL includes /v1
Test the API key: curl -H "x-api-key: YOUR_KEY" https://us.api.flexprice.io/v1/customers

API connection issues

Credentials: Verify API key and base URL are correct
Network: Check firewall/proxy settings
Rate limiting: Reduce request frequency if hitting rate limits

Server not appearing in client

Restart your MCP client after adding configuration
Check for JSON syntax errors in config file
Verify Node.js 20+ is installed: node --version

Missing dependencies (local repo)

Run npm install and npm run build in the server directory

Docker container exits

Check logs: docker logs <container_id>
Verify environment variables are passed correctly
Try docker run -it --rm flexprice-mcp printenv to inspect env

Regenerating the Server

The MCP server is generated from a filtered OpenAPI spec. To regenerate after API changes:

Update API spec

Run make swagger from the repo root to regenerate the OpenAPI spec

Filter spec for MCP

Run make filter-mcp-spec to create the filtered spec with allowed tags

Generate MCP server

Run make sdk-all to regenerate all SDKs including the MCP server

Merge custom files

Run make merge-custom to merge custom README and code into the output

See the main repository README and AGENTS.md for detailed SDK/MCP generation and publishing workflows.

Next Steps

API Reference

Complete FlexPrice API documentation

MCP Specification

Learn more about Model Context Protocol

NPM Package

View package on npm

GitHub Repository

MCP server source code

Client Libraries

​Prerequisites

Node.js

npm

API Key

​Quick Start

​Installation Methods

​Add to Your MCP Client

​Cursor

​VS Code

​Claude Code

​Claude Desktop

​Available Tools

​Dynamic Mode (Progressive Discovery)

​Scopes (Optional)

​Example Usage

​Alternative Configurations

​Local Repository (Node)

​Docker

​Troubleshooting

​Regenerating the Server

​Next Steps

API Reference

MCP Specification

NPM Package

GitHub Repository

Prerequisites

Quick Start

Installation Methods

Add to Your MCP Client

Cursor

VS Code

Claude Code

Claude Desktop

Available Tools

Dynamic Mode (Progressive Discovery)

Scopes (Optional)

Example Usage

Alternative Configurations

Local Repository (Node)

Docker

Troubleshooting

Regenerating the Server

Next Steps