@flexprice/mcp-server 0.0.3 → 2.0.0

package/README.md

@@ -1,67 +1,84 @@
-# FlexPrice MCP Server
+# flexprice MCP Server
 
-A Model Context Protocol (MCP) server that enables AI agents to access FlexPrice API (customers, plans, prices, subscriptions, invoices, payments, events, etc.) via tools.
+A Model Context Protocol (MCP) server that exposes the flexprice API as tools for AI assistants (e.g. Claude, Cursor, VS Code, Windsurf). Use it to manage customers, plans, prices, subscriptions, invoices, payments, events, and more from your IDE or CLI.
+
+## Table of contents
+
+- [Prerequisites](#prerequisites)
+- [How to use the flexprice MCP server](#how-to-use-the-flexprice-mcp-server)
+- [Add to your MCP client](#add-to-your-mcp-client)
+- [Tools](#tools)
+- [Progressive discovery (dynamic mode)](#progressive-discovery-dynamic-mode)
+- [Scopes](#scopes)
+- [Troubleshooting](#troubleshooting)
+- [Generating the MCP server](#generating-the-mcp-server)
 
 ## Prerequisites
 
-- Node.js (v20 or higher)
-- npm or yarn
-- FlexPrice API key (obtained from your FlexPrice account)
-- **For generating the server:** [Speakeasy CLI](https://www.speakeasy.com/) (see [Generating the MCP server](#generating-the-mcp-server))
+- **Node.js** v20 or higher
+- **npm** or **yarn**
+- **flexprice API key** from your [flexprice account](https://app.flexprice.io)
 
-## How you can use the FlexPrice MCP server
+## How to use the flexprice MCP server
 
-You can use the FlexPrice MCP server in two ways: **npm package** (one command) or **local repo** (clone and run). Pick one option below, then [add it to your MCP client](#add-to-your-mcp-client).
+You can run the server in two ways: **npm package** (one command) or **local repo** (clone and run). Pick one, then [add it to your MCP client](#add-to-your-mcp-client).
 
 ---
 
-### Option 1: Use the npm package
+### Option 1: npm package
+
+Install: `npm i @flexprice/mcp-server`. Or run with one command (no clone or build):
+
+```bash
+npx @flexprice/mcp-server start --server-url https://us.api.flexprice.io/v1 --api-key-auth YOUR_API_KEY
+```
 
-- **What:** Run the server with one command (`npx`); no clone or build.
-- **Run:**
-  ```bash
-  npx @flexprice/mcp-server start --server-url https://api.cloud.flexprice.io/v1 --api-key-auth YOUR_API_KEY
-  ```
-- **Next step:** [Add to your MCP client](#add-to-your-mcp-client) and use the config for your editor below.
+Replace `YOUR_API_KEY` with your flexprice API key. Next: [Add to your MCP client](#add-to-your-mcp-client).
 
 ---
 
-### Option 2: Run from the local repo
-
-- **What:** Clone the repo, install, build, and run. Use this if you want to change code or run without npm.
-- **Steps:**
-  1. Clone the repository: `git clone <repository-url> && cd mcp-server`
-  2. Install dependencies: `npm install`
-  3. Create a `.env` file (copy from `.env.example`) with `BASE_URL=https://api.cloud.flexprice.io/v1` and `API_KEY_APIKEYAUTH=your_api_key_here`. `BASE_URL` must include `/v1` (no trailing slash).
-  4. Build: `npm run build`
-  5. Start: `npm start`
-- **Optional — Docker (stdio):** Build and run with stdio instead of cloning into your client:
-  ```bash
-  docker build -t flexprice-mcp .
-  docker run -i -e API_KEY_APIKEYAUTH=your_api_key_here -e BASE_URL=https://api.cloud.flexprice.io/v1 flexprice-mcp node bin/mcp-server.js start
-  ```
-- **Next step:** [Add to your MCP client](#add-to-your-mcp-client) and use the **Node from repo** or **Docker** config for your editor.
+### Option 2: Local repo
+
+Use this if you want to change code or run without npm:
+
+1. Clone the repository and go to the MCP server directory (e.g. `api/mcp` or the repo that contains it).
+2. Install dependencies: `npm install`
+3. Create a `.env` file (from `.env.example` if present) with:
+   - `BASE_URL=https://us.api.flexprice.io/v1` (must include `/v1`; no trailing space or trailing slash)
+   - `API_KEY_APIKEYAUTH=your_api_key_here`
+4. Build: `npm run build`
+5. Start: `npm start`
+
+**Docker (stdio):** You can also build and run with stdio:
+
+```bash
+docker build -t flexprice-mcp .
+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
+```
+
+Next: [Add to your MCP client](#add-to-your-mcp-client) and use the **Node from repo** or **Docker** config below.
 
 ## Add to your MCP client
 
-Add the FlexPrice MCP server in your editor using one of the configs below. Replace `YOUR_API_KEY` with your FlexPrice API key in all examples.
+Add the flexprice MCP server in your editor. Replace `YOUR_API_KEY` with your flexprice API key in all examples. Example config snippets are in [examples/](examples/).
+
+**After connecting:** In Cursor, open the MCP panel and confirm the server is connected. You can list tools and try an operation (e.g. list customers) from your assistant. In Claude, use `/mcp` to see connected servers and available tools.
 
 ### Config file locations
 
-| Host                         | Config location                                                                                                                                           |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Cursor**                   | **Cursor → Settings → MCP** (or **Cmd + Shift + P** → "Cursor Settings" → MCP). Edit the MCP servers list or the JSON file it uses.                        |
-| **VS Code**                  | Command Palette → **MCP: Open User Configuration** (opens `mcp.json`).                                                                                    |
-| **Claude Desktop (macOS)**   | `~/Library/Application Support/Claude/claude_desktop_config.json`                                                                                         |
-| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json`                                                                                                             |
+| Host                       | Config location |
+| -------------------------- | --------------- |
+| **Cursor**                 | Cursor → Settings → MCP (or Cmd+Shift+P → "Cursor Settings" → MCP) |
+| **VS Code**                | Command Palette → **MCP: Open User Configuration** (opens `mcp.json`) |
+| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
 
 ---
 
 ### Cursor
 
 1. Open **Cursor → Settings → Cursor Settings** and go to the **MCP** tab.
-2. Click **+ Add new global MCP server** (or open the MCP configuration file).
-3. Paste the following (Option 1 — npx) or use an [alternative config](#alternative-configs) for Option 2. Save and restart Cursor if the server does not appear.
+2. Add a new MCP server and use this config (Option 1 — npx):
 
 ```json
 {
@@ -73,7 +90,7 @@ Add the FlexPrice MCP server in your editor using one of the configs below. Repl
         "@flexprice/mcp-server",
         "start",
         "--server-url",
-        "https://api.cloud.flexprice.io/v1",
+        "https://us.api.flexprice.io/v1",
         "--api-key-auth",
         "YOUR_API_KEY"
       ]
@@ -86,8 +103,8 @@ Add the FlexPrice MCP server in your editor using one of the configs below. Repl
 
 ### VS Code
 
-1. Open the Command Palette (**Ctrl+Shift+P** / **Cmd+Shift+P**) and run **MCP: Add Server** or **MCP: Open User Configuration**.
-2. Add the stdio config below (or use an [alternative config](#alternative-configs) for Option 2).
+1. Open Command Palette (**Ctrl+Shift+P** / **Cmd+Shift+P**) and run **MCP: Open User Configuration** or **MCP: Add Server**.
+2. Add:
 
 ```json
 {
@@ -100,7 +117,7 @@ Add the FlexPrice MCP server in your editor using one of the configs below. Repl
         "@flexprice/mcp-server",
         "start",
         "--server-url",
-        "https://api.cloud.flexprice.io/v1",
+        "https://us.api.flexprice.io/v1",
         "--api-key-auth",
         "YOUR_API_KEY"
       ]
@@ -113,10 +130,8 @@ Add the FlexPrice MCP server in your editor using one of the configs below. Repl
 
 ### Claude Code
 
-Run:
-
 ```bash
-claude mcp add FlexPrice -- npx -y @flexprice/mcp-server start --server-url https://api.cloud.flexprice.io/v1 --api-key-auth YOUR_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
 ```
 
 Then run `claude` and use `/mcp` to confirm the server is connected.
@@ -125,7 +140,7 @@ Then run `claude` and use `/mcp` to confirm the server is connected.
 
 ### Claude Desktop
 
-Add the config below to your Claude Desktop config file (path above).
+Add to your Claude Desktop config file (path in the table above):
 
 ```json
 {
@@ -137,7 +152,7 @@ Add the config below to your Claude Desktop config file (path above).
         "@flexprice/mcp-server",
         "start",
         "--server-url",
-        "https://api.cloud.flexprice.io/v1",
+        "https://us.api.flexprice.io/v1",
         "--api-key-auth",
         "YOUR_API_KEY"
       ]
@@ -162,7 +177,7 @@ Quit and reopen Claude Desktop.
       "args": ["/path/to/mcp-server/bin/mcp-server.js", "start"],
       "env": {
         "API_KEY_APIKEYAUTH": "your_api_key_here",
-        "BASE_URL": "https://api.cloud.flexprice.io/v1"
+        "BASE_URL": "https://us.api.flexprice.io/v1"
       }
     }
   }
@@ -179,319 +194,78 @@ Quit and reopen Claude Desktop.
       "args": ["run", "-i", "--rm", "-e", "API_KEY_APIKEYAUTH", "-e", "BASE_URL", "flexprice-mcp"],
       "env": {
         "API_KEY_APIKEYAUTH": "your_api_key_here",
-        "BASE_URL": "https://api.cloud.flexprice.io/v1"
+        "BASE_URL": "https://us.api.flexprice.io/v1"
       }
     }
   }
 }
 ```
 
-After editing, save the file and **restart Cursor or quit and reopen Claude Desktop** so the MCP server is picked up.
+After editing, save and **restart Cursor or quit and reopen Claude Desktop** so the MCP server is loaded.
 
 ## Tools
 
-The server exposes the FlexPrice API as MCP tools. Tool names and parameters match the OpenAPI spec. For the full list of tools, see `swagger/swagger-3-0.json` or your MCP client's tool list (e.g. Cursor and Claude show all available tools once the server is connected).
-
-## Troubleshooting
-
-### "Invalid URL" or request errors when calling tools
-
-- **Cause:** The server builds request URLs from `process.env.BASE_URL` + the path (e.g. `/customers`). If `BASE_URL` is not set, the URL is invalid. If `BASE_URL` omits `/v1`, you may get **404** because the API expects the base to include `/v1`.
-- **Fix:**
-  1. When running locally: create a `.env` in the project root with `BASE_URL=https://api.cloud.flexprice.io/v1` (or `https://api-dev.cloud.flexprice.io/v1` for dev). No trailing slash after `v1`. Then run `npm run start` again.
-  2. When using Cursor or Claude: in the MCP server config, add `"BASE_URL": "https://api.cloud.flexprice.io/v1"` to the `env` object for the `flexprice` server.
-  3. Quick test from the repo root: `BASE_URL=https://api.cloud.flexprice.io/v1 API_KEY_APIKEYAUTH=your_key npm run start`.
-  4. If you get **404** on tool calls, ensure `BASE_URL` includes `/v1`.
-
-### API Connection Issues
-
-1. **Verify API Credentials**: Ensure your API key and base URL are correct (check `.env` for local setup or env vars for Docker; test the key against the FlexPrice API).
-
-2. **Network Connectivity**: Confirm that your server can reach the FlexPrice API endpoints:
-
-   ```bash
-   curl -H "x-api-key: your_api_key_here" https://api.cloud.flexprice.io/v1/customers
-   ```
-
-3. **Rate Limiting**: If you're getting rate limit errors, reduce the frequency of requests or contact FlexPrice support.
-
-### Server Issues
-
-1. **Port Conflicts**: If you see an error about port 3000 being in use, change the port in your configuration or stop the process: `lsof -i :3000` then `kill -9 PID`.
-
-2. **Missing Dependencies**:
-
-   ```bash
-   npm install
-   npm run build
-   ```
-
-3. **Permission Issues**:
-
-   ```bash
-   chmod +x bin/mcp-server.js
-   ```
-
-### Docker Issues
-
-1. **Docker Build Failures**: Check Docker installation (`docker --version`), ensure the daemon is running, try rebuilding with `--no-cache`.
-
-2. **Container Exit**: Inspect logs with `docker logs $(docker ps -lq)`.
-
-3. **Environment Variables**: Verify env vars are passed: `docker run -it --rm flexprice-mcp printenv`.
-
-## Testing
-
-The project uses Jest for unit testing. Test files live under `src/__tests__/` or alongside source with `*.test.ts` / `*.spec.ts`.
-
-```bash
-npm test
-npm run test:watch
-npm run test:coverage
-npm run test:ci
-```
-
-See [TESTING.md](TESTING.md) for the testing guide and [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow.
-
-## Generating the MCP server
-
-The server is generated with **Speakeasy** from `swagger/swagger-3-0.json`. Generate when setting up the repo or after changing the OpenAPI spec.
-
-**1. Install the Speakeasy CLI** (one-time)
-
-- **macOS (Homebrew):** `brew install speakeasy-api/tap/speakeasy`
-- **macOS/Linux (script):** `curl -fsSL https://go.speakeasy.com/cli-install.sh | sh`
-
-**2. Generate the server**
-
-From the repo root:
-
-```bash
-# Generate only (output at repo root; may overwrite package.json)
-npm run generate
-
-# Generate, restore repo scripts in package.json, and install dependencies (recommended)
-npm run generate:install
-```
-
-Or run Speakeasy directly:
-
-```bash
-speakeasy run --target flexprice-mcp -y
-```
-
-Then restore package.json scripts and install deps:
-
-```bash
-node scripts/merge-package-after-generate.cjs
-npm install
-```
-
-**3. Build and run**
-
-```bash
-npm run build
-npm start
-```
-
-Generated output is at the repo root (`src/`, `bin/mcp-server.js`, etc.). You can edit these files; re-run `npm run generate` or `npm run generate:install` after changing `swagger/swagger-3-0.json` or `.speakeasy/overlays.yaml`. The files `src/mcp-server/build.mts` and `src/mcp-server/cli/start/command.ts`, `impl.ts` are listed in `.genignore` so Speakeasy does not overwrite them (build uses Node/esbuild; CLI uses env vars `BASE_URL` and `API_KEY_APIKEYAUTH` for Cursor MCP). The merge script restores `package.json` scripts and deps after generation.
-
-## Development
-
-To change the API surface: edit `swagger/swagger-3-0.json` (or `.speakeasy/overlays.yaml` for retries), then run `npm run generate:install`, `npm run build`, and `npm start`. See [CONTRIBUTING.md](CONTRIBUTING.md) for scripts and [TESTING.md](TESTING.md) for tests.
-
-## License
-
-This project is licensed under the [Apache License 2.0](LICENSE).
-
-<!-- Start Summary [summary] -->
-## Summary
-
-FlexPrice API: FlexPrice API Service
-<!-- End Summary [summary] -->
-
-<!-- Start Table of Contents [toc] -->
-## Table of Contents
-<!-- $toc-max-depth=2 -->
-* [FlexPrice MCP Server](#flexprice-mcp-server)
-  * [Prerequisites](#prerequisites)
-  * [How you can use the FlexPrice MCP server](#how-you-can-use-the-flexprice-mcp-server)
-* [Generate only (output at repo root; may overwrite package.json)](#generate-only-output-at-repo-root-may-overwrite-packagejson)
-* [Generate, restore repo scripts in package.json, and install dependencies (recommended)](#generate-restore-repo-scripts-in-packagejson-and-install-dependencies-recommended)
-
-<!-- End Table of Contents [toc] -->
-
-<!-- Start Installation [installation] -->
-## Installation
-
-Same configs as above, in collapsible form for Cursor, VS Code, Claude Code, etc.
-
-> [!TIP]
-> To finish publishing your MCP Server to npm and others you must [run your first generation action](https://www.speakeasy.com/docs/github-setup#step-by-step-guide).
-<details>
-<summary>Claude Desktop</summary>
-
-Install the MCP server as a Desktop Extension using the pre-built [`mcp-server.mcpb`](./mcp-server.mcpb) file:
-
-Simply drag and drop the [`mcp-server.mcpb`](./mcp-server.mcpb) file onto Claude Desktop to install the extension.
-
-The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.
+The server exposes flexprice API operations as MCP tools. **Only operations with certain OpenAPI tags are included** (e.g. Customers, Invoices, Events). The allowed tags are configured in the repo; the filtered spec is `docs/swagger/swagger-3-0-mcp.json`. Tool names and parameters follow the OpenAPI spec. For the full list, see your MCP client’s tool list after connecting, or the OpenAPI spec (e.g. `docs/swagger/swagger-3-0.json`) in the repo.
 
-> [!NOTE]
-> MCP bundles provide a streamlined way to package and distribute MCP servers. Learn more about [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).
+## Progressive discovery (dynamic mode)
 
-</details>
+Servers with many tools can bloat context and token usage. **Dynamic mode** exposes a small set of meta-tools so the assistant can discover and call operations on demand:
 
-<details>
-<summary>Cursor</summary>
+- **`list_tools`** – List available tools with names and descriptions  
+- **`describe_tool`** – Get the input schema for one or more tools  
+- **`execute_tool`** – Run a tool by name with given parameters  
 
-[One-click install (local)](cursor://anysphere.cursor-deeplink/mcp/install?name=FlexPrice&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBmbGV4cHJpY2UvbWNwLXNlcnZlciIsInN0YXJ0IiwiLS1zZXJ2ZXItdXJsIiwiaHR0cHM6Ly9hcGkuY2xvdWQuZmxleHByaWNlLmlvL3YxIiwiLS1hcGkta2V5LWF1dGgiLCJZT1VSX0FQSV9LRVkiXX0=)
-
-Or manually add a stdio server:
+To enable dynamic mode, add `--mode dynamic` when starting the server:
 
 ```json
-{
-  "mcpServers": {
-    "flexprice": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@flexprice/mcp-server",
-        "start",
-        "--server-url",
-        "https://api.cloud.flexprice.io/v1",
-        "--api-key-auth",
-        "YOUR_API_KEY"
-      ]
-    }
-  }
-}
+"args": ["-y", "@flexprice/mcp-server", "start", "--server-url", "https://us.api.flexprice.io/v1", "--api-key-auth", "YOUR_API_KEY", "--mode", "dynamic"]
 ```
 
-Replace `YOUR_API_KEY` with your FlexPrice API key.
+This reduces tokens per request and can improve tool choice when there are many operations.
 
-</details>
+## Scopes
 
-<details>
-<summary>Claude Code CLI</summary>
+If the server is configured with scopes (e.g. `read`, `write`), you can limit tools by scope:
 
 ```bash
-claude mcp add FlexPrice -- npx -y @flexprice/mcp-server start --server-url https://api.cloud.flexprice.io/v1 --api-key-auth YOUR_API_KEY
+npx @flexprice/mcp-server start --server-url https://us.api.flexprice.io/v1 --api-key-auth YOUR_API_KEY --scope read
 ```
 
-Replace `YOUR_API_KEY` with your FlexPrice API key.
-
-</details>
-<details>
-<summary>Gemini</summary>
-
-```bash
-gemini mcp add FlexPrice -- npx -y @flexprice/mcp-server start --server-url https://api.cloud.flexprice.io/v1 --api-key-auth YOUR_API_KEY
-```
+Use `read` for read-only access when the server defines a `read` scope.
 
-Replace `YOUR_API_KEY` with your FlexPrice API key.
-
-</details>
-<details>
-<summary>Windsurf</summary>
-
-Refer to [Official Windsurf documentation](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin) for latest information
-
-1. Open Windsurf Settings
-2. Select Cascade on left side menu
-3. Click on `Manage MCPs`. (To Manage MCPs you should be signed in with a Windsurf Account)
-4. Click on `View raw config` to open up the mcp configuration file.
-5. If the configuration file is empty paste the full json (replace `YOUR_API_KEY`):
-
-```json
-{
-  "mcpServers": {
-    "flexprice": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@flexprice/mcp-server",
-        "start",
-        "--server-url",
-        "https://api.cloud.flexprice.io/v1",
-        "--api-key-auth",
-        "YOUR_API_KEY"
-      ]
-    }
-  }
-}
-```
-</details>
-<details>
-<summary>VS Code</summary>
-
-[Install in VS Code](vscode://ms-vscode.vscode-mcp/install?name=FlexPrice&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBmbGV4cHJpY2UvbWNwLXNlcnZlciIsInN0YXJ0IiwiLS1zZXJ2ZXItdXJsIiwiaHR0cHM6Ly9hcGkuY2xvdWQuZmxleHByaWNlLmlvL3YxIiwiLS1hcGkta2V5LWF1dGgiLCJZT1VSX0FQSV9LRVkiXX0=)
-
-Or manually: Refer to [Official VS Code documentation](https://code.visualstudio.com/api/extension-guides/ai/mcp). Open `MCP: Open User Configuration` and add (replace `YOUR_API_KEY`):
-
-```json
-{
-  "mcpServers": {
-    "flexprice": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@flexprice/mcp-server",
-        "start",
-        "--server-url",
-        "https://api.cloud.flexprice.io/v1",
-        "--api-key-auth",
-        "YOUR_API_KEY"
-      ]
-    }
-  }
-}
-```
-
-</details>
-<details>
-<summary>Stdio installation via npm</summary>
+## Troubleshooting
 
-To start the MCP server locally, run:
+### "Invalid URL" or request errors
 
-```bash
-npx @flexprice/mcp-server start --server-url https://api.cloud.flexprice.io/v1 --api-key-auth YOUR_API_KEY
-```
+- The server builds request URLs from `BASE_URL` + path. If `BASE_URL` is unset or wrong, requests fail.
+- **Fix:** Set `BASE_URL=https://us.api.flexprice.io/v1` (no trailing space or slash after `v1`). For npx, pass `--server-url https://us.api.flexprice.io/v1`.
+- If you get **404** on tool calls, ensure the base URL includes `/v1`.
 
-For a full list of server arguments, run:
+### API connection issues
 
-```bash
-npx @flexprice/mcp-server --help
-```
+1. **Credentials:** Check that your API key and base URL are correct. Test the key with the flexprice API (e.g. `curl -H "x-api-key: your_key" https://us.api.flexprice.io/v1/customers`).
+2. **Network:** Confirm the host can reach the flexprice API (firewall, proxy).
+3. **Rate limiting:** If you see rate-limit errors, reduce request frequency or contact flexprice support.
 
-</details>
-<!-- End Installation [installation] -->
+### Server issues
 
-<!-- Start Progressive Discovery [dynamic-mode] -->
-## Progressive Discovery
+- **Port in use:** If something else uses the port (e.g. 3000), change the server config or stop the other process.
+- **Missing dependencies:** Run `npm install` and `npm run build` in the server directory.
+- **Permissions:** Ensure the entrypoint is executable (e.g. `chmod +x bin/mcp-server.js`).
 
-MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.
+### Docker
 
-To enable dynamic mode, pass the `--mode dynamic` flag when starting your server:
+- **Build failures:** Check Docker is installed and the daemon is running; try `docker build --no-cache`.
+- **Container exits:** Inspect logs with `docker logs <container_id>`.
+- **Env vars:** Verify env is passed: `docker run -it --rm flexprice-mcp printenv`.
 
-```jsonc
-{
-  "mcpServers": {
-    "flexprice": {
-      "command": "npx",
-      "args": ["-y", "@flexprice/mcp-server", "start", "--server-url", "https://api.cloud.flexprice.io/v1", "--api-key-auth", "YOUR_API_KEY", "--mode", "dynamic"]
-    }
-  }
-}
-```
-
-In dynamic mode, the server registers only the following meta-tools instead of every individual tool:
+## Generating the MCP server
 
-- **`list_tools`**: Lists all available tools with their names and descriptions.
-- **`describe_tool`**: Returns the input schema for one or more tools by name.
-- **`execute_tool`**: Executes a tool by name with the provided input parameters.
+The server is generated from a tag-filtered OpenAPI spec (`docs/swagger/swagger-3-0-mcp.json`), not the full spec. Only operations whose tags are listed in the allowed-tags configuration are included. To regenerate after API or overlay changes:
 
-This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.
-<!-- End Progressive Discovery [dynamic-mode] -->
+1. (Optional) Edit the allowed-tags configuration to add or remove tags; then run `make filter-mcp-spec` to rebuild the filtered spec.
+2. From the repo root, run `make sdk-all` (this runs `filter-mcp-spec` automatically, then generates the MCP server).
+3. Run `make merge-custom` so custom files (including this README) are merged into the output.
+4. Build and run: `npm run build` and `npm start` from the MCP output directory.
 
-<!-- Placeholder for Future Speakeasy SDK Sections -->
+See the main repo README and AGENTS.md for SDK/MCP generation and publishing.