MCP Server

@kelviq/mcp-server is the official Model Context Protocol server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Antigravity — and exposes the full Kelviq API as typed tools that the LLM can call directly, plus the entire Kelviq documentation as searchable resources. Instead of asking your assistant to “write me a curl command,” you describe the outcome (“create a Pro plan under product X and publish it”) and it does the work in a single turn.

Using Claude Code? The fastest install is the Agent Toolkit plugin — two commands set up this MCP server and five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.

45 tools spanning customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus 69 resources including the full OpenAPI spec, and 3 guided prompts for the most common workflows. Every tool carries MCP safety annotations, so clients can auto-approve read-only calls while confirming destructive ones.

How It Works

The server runs locally on your machine as a Node process started by your AI client. It speaks the MCP stdio transport — your client launches npx -y @kelviq/mcp-server, connects over stdio, and discovers the tools and resources advertised by the server. When the LLM decides to call a Kelviq tool, the server:

Validates the LLM-provided arguments against a Zod schema derived from Kelviq’s OpenAPI spec.
Adds your API key as a Bearer token and sends the HTTPS request to the appropriate Kelviq host.
Returns the JSON response (or a structured {"error": {...}} object) back to the LLM.

API errors are returned as content, not exceptions — the LLM reads them and reacts (retries with a fix, asks you to clarify, etc).

Step 1: Get Your API Keys

Sign in at app.kelviq.com.
Navigate to Settings → API Keys.
Copy:
- Server API Key — required for all API tools.
- Client API Key — required only for the promotion_get tool.

Never commit API keys to version control or paste them into shared chats. Use your MCP client’s env configuration mechanism — most clients store secrets in their own credentials file.

Step 2: Add the Server to Your AI Client

Every client uses the same underlying command — npx -y @kelviq/mcp-server — with your two keys passed as environment variables. What differs is the config file location and, in a few cases, the root JSON key. Pick the tab for your client.

claude mcp add kelviq \
  --env KELVIQ_SERVER_API_KEY=<your-server-key> \
  --env KELVIQ_CLIENT_API_KEY=<your-client-key> \
  -- npx -y @kelviq/mcp-server

The -- separator is required so that claude doesn’t intercept -y as one of its own flags. Put all --env arguments before the --.

Verify the connection with /mcp inside a Claude Code session — you should see kelviq ✓ Connected, 45 tools.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent for your OS:

{
  "mcpServers": {
    "kelviq": {
      "command": "npx",
      "args": ["-y", "@kelviq/mcp-server"],
      "env": {
        "KELVIQ_SERVER_API_KEY": "server-...",
        "KELVIQ_CLIENT_API_KEY": "client-..."
      }
    }
  }
}

Restart Claude Desktop — the hammer icon shows kelviq with all tools.

Open Cursor Settings → Tools and MCP → Add new MCP server, or edit .cursor/mcp.json (project) / ~/.cursor/mcp.json (global) directly:

{
  "mcpServers": {
    "kelviq": {
      "command": "npx",
      "args": ["-y", "@kelviq/mcp-server"],
      "env": {
        "KELVIQ_SERVER_API_KEY": "server-...",
        "KELVIQ_CLIENT_API_KEY": "client-..."
      }
    }
  }
}

Project-level config overrides global config when a server of the same name exists in both.

As of June 2026, Windsurf was rebranded Devin Desktop by Cognition. Existing installs update automatically — same editor, new name. The MCP config location also changed with the rebrand:

Devin Desktop (current): %APPDATA%\devin\config.json (Windows) — via Settings → Devin Local → Configuration → MCP servers
Legacy Windsurf installs: ~/.codeium/windsurf/mcp_config.json

Add Kelviq under the mcpServers key:

{
  "mcpServers": {
    "kelviq": {
      "command": "npx",
      "args": ["-y", "@kelviq/mcp-server"],
      "env": {
        "KELVIQ_SERVER_API_KEY": "server-...",
        "KELVIQ_CLIENT_API_KEY": "client-..."
      }
    }
  }
}

Save, then refresh or restart the app — kelviq should appear under MCP servers in Settings, where you can enable it and toggle individual tools.

If your config.json isn’t empty, check its existing top-level structure before pasting — merge kelviq alongside whatever’s already there rather than overwriting the file.

Add a .vscode/mcp.json in your workspace, or run “MCP: Open User Configuration” from the Command Palette for a global mcp.json. VS Code uses servers, not mcpServers, as the root key:

{
  "servers": {
    "kelviq": {
      "command": "npx",
      "args": ["-y", "@kelviq/mcp-server"],
      "env": {
        "KELVIQ_SERVER_API_KEY": "server-...",
        "KELVIQ_CLIENT_API_KEY": "client-..."
      }
    }
  }
}

Save, then click the Start CodeLens above the kelviq entry (or reload the window) and confirm it under the tools icon in Copilot Chat’s Agent mode.

Already have Kelviq configured in Cursor or Windsurf? Under Settings → Chat → MCP → Discovery, check the matching box (e.g. “Windsurf configurations”) to auto-import that server instead of retyping it. You can also use the inputs array to be prompted for the keys instead of storing them in plaintext.

Open the ”…” menu in the Agent panel → MCP Servers → Manage MCP Servers → View raw config. This opens mcp_config.json at:

Windows: C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json
macOS/Linux: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "kelviq": {
      "command": "npx",
      "args": ["-y", "@kelviq/mcp-server"],
      "env": {
        "KELVIQ_SERVER_API_KEY": "server-...",
        "KELVIQ_CLIENT_API_KEY": "client-..."
      }
    }
  }
}

The Antigravity CLI (as opposed to the IDE) uses a separate config path: ~/.gemini/antigravity-cli/mcp_config.json.

Any client supporting stdio MCP servers works. Point it at:

npx -y @kelviq/mcp-server

with the env vars listed below.

Step 3: Try It

In a new session, type a prompt like:

Search Kelviq docs for license keys.

List my Kelviq products.

Your AI client should pick the right tool, call it, and show the result inline. If you see a Configuration error, your env vars didn’t make it through — re-check the config above.

Environment Variables

Variable	Required	Default	Purpose
`KELVIQ_SERVER_API_KEY`	Yes, for all API tools	—	Server API key (Bearer token for the core API)
`KELVIQ_CLIENT_API_KEY`	Only for `promotion_get`	—	Client API key (Bearer token for the edge host)
`KELVIQ_ENV`	No	`production`	Set to `sandbox` to target your sandbox environment — switches both API hosts automatically. Use a sandbox key with it: keys only work against their own environment.
`KELVIQ_BASE_URL`	No	per `KELVIQ_ENV`	Advanced: override the core API host
`KELVIQ_EDGE_URL`	No	per `KELVIQ_ENV`	Advanced: override the edge host (entitlements + promotions)

Docs tools (docs_search, docs_read) work with no API keys at all. Even without a key, the LLM can answer Kelviq questions from the bundled documentation.

Point at Staging

KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1

Pair these with a staging-scoped Server API Key from your dashboard’s staging environment.

Tool Reference

Tools are grouped by domain. Each tool name uses domain_action form (customer_create, plan_publish). The LLM picks the right tool from the description automatically — you rarely need to name a tool explicitly.

Customers

Tool	Description
`customer_create`	Create a customer. Required: `customerId`. Optional: `email`, `name`, `metadata`, `billingAddress`.
`customer_update`	Patch an existing customer by `customerId`. Only fields you pass are updated.

Checkout & Portal

Tool	Description
`checkout_create_session`	Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`.
`portal_session_create`	Create a customer portal session. Share the returned `signedPortalUrl` with the customer — the bare `customerPortalUrl` does not authenticate on its own.

Subscriptions

Tool	Description
`subscription_create`	Create a subscription directly (skip checkout). Requires off-session charging to be enabled for your organization — otherwise use `checkout_create_session`.
`subscription_list`	List subscriptions, filter by customer, paginated.
`subscription_update`	Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade.
`subscription_cancel`	Cancel `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, or `SPECIFIC_DATE`.

Entitlements, Licenses, Usage

Tool	Description
`entitlements_get`	Fetch entitlements for a customer. Pass `featureId` to scope.
`license_activate`	Activate a license key for a specific instance. Returns `instanceId`.
`license_deactivate`	Deactivate a license instance.
`license_validate`	Validate a license key (optionally bound to an instance).
`usage_report`	Report metered usage. `behaviour: SET` replaces, `DELTA` increments.

Offerings & Promotions

Tool	Description
`offering_get_product`	Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state.
`promotion_get`	Resolve the active promotion for the caller’s location. Uses Client API key.

Catalog: Products

Tool	Description
`product_list`	List catalog products. Optional `search` substring + `page`.
`product_create`	Create a product. Required: `name`, `taxCode`. Optional `imageKeys` (S3 file keys from the `POST /media/` API endpoint).
`product_retrieve`	Fetch one product by UUID or identifier.
`product_update`	Patch a product.
`product_archive`	Archive (soft-delete) a product.
`product_settings_get`	VPN / Tor / proxy policy, default currency, product URL.
`product_settings_update`	Patch any subset of those settings.
`product_image_update`	Edit display fields of a product image (`name`, `ordering`, `thumbnail`, `enabled`).
`product_image_delete`	Remove an image from a product.

Catalog: Features

Tool	Description
`feature_list`	List catalog features.
`feature_create`	Create a feature. Required: `name`, `featureType` (`BOOLEAN` / `CUSTOMIZABLE` / `METER`).
`feature_retrieve`	Fetch one feature.
`feature_archive`	Archive a feature. Plans referencing it keep working.

Catalog: Plans

Plans are versioned. Updates create a draft; plan_publish releases it.

Tool	Description
`plan_list`	List all plans in the account.
`plan_create`	Create a plan under a product. Plan starts in `DRAFT`.
`plan_retrieve`	Fetch one plan.
`plan_update`	Patch a plan. Updates to a published plan automatically create a new draft.
`plan_archive`	Archive a plan. Existing subscriptions keep working.
`plan_publish`	Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers.
`plan_discard_draft`	Drop the current draft, keep the published version.
`plan_prices_list`	List all prices configured on a plan.
`plan_entitlements_list`	List feature entitlements on a plan.
`plan_entitlements_add`	Attach feature entitlements.
`plan_entitlement_update`	Patch a single entitlement’s `details`.
`plan_entitlement_delete`	Remove an entitlement.
`plan_file_update`	Edit display fields of a plan-attached file.
`plan_file_delete`	Remove a file from a plan.
`plan_file_download`	Download URL/stream for a plan file (buyer-facing deliverables).

Docs (no API key required)

Tool	Description
`docs_search`	Full-text search across the bundled Kelviq docs. Returns `{slug, title, snippet, score}`.
`docs_read`	Fetch a full markdown doc by slug.

Resources

Resources let your AI client pin pages into context. The server advertises three categories:

URI pattern	Content
`kelviq://docs/{section}/{slug}`	Every conceptual page in the Kelviq docs (~59 pages)
`kelviq://openapi.json`	The full OpenAPI 3.0 spec (49 operations, every schema)
`kelviq://README`	Top-level Kelviq overview

For exhaustive per-endpoint request/response shapes, the OpenAPI spec is the source of truth. Ask your assistant “check the OpenAPI spec for createSubscription” and it will read the resource directly.

Built-in Prompts

The server ships three MCP prompts that encode Kelviq’s golden-path workflows — including the gotchas (plans start as invisible drafts until published; entitlements attach by feature UUID; pricing is set in the dashboard or with the Kelviq CLI, not through the MCP server). In Claude Code they appear as slash commands (e.g. /kelviq:setup_product); other MCP clients list them under prompts.

Prompt	Arguments	What it guides
`setup_product`	`productName?`, `planName?`	Full catalog bootstrap: product → features → plan → entitlements → publish → verify.
`launch_plan`	`productId?`, `planName?`	Add and publish a new plan on an existing product, reusing existing features.
`diagnose_customer`	`customerId`	Cross-check a customer’s entitlements, subscriptions, and plan configuration; ends with concrete next actions.

Example Prompts

Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:

Build a catalog from scratch

Create a Kelviq product called “Notion Plus” with tax code saas, then create three plans (Free, Pro Monthly, Pro Yearly), add an api-calls feature with limits 1000 / 50000 / unlimited, and publish all three plans.

Calls (in order): product_create → feature_create → plan_create × 3 → plan_entitlements_add × 3 → plan_publish × 3. Set each plan’s prices in the dashboard or with the Kelviq CLI, which manages pricing as reviewable code.

Issue a checkout link

Create a checkout session for plan pro-monthly for a new customer, success URL https://example.com/done.

Calls: checkout_create_session. Returns the checkoutUrl you can hand to your buyer.

License key management

Activate license LIC-ABCDE for customer geojacob, instance name “MacBook Pro M3”, then validate it.

Calls: license_activate → license_validate.

Inspect customer state

Show me all subscriptions for customer acme-42 and tell me which features they have access to.

Calls: subscription_list → entitlements_get.

Documentation lookup

How do digital downloads work in Kelviq? What’s the file-size limit?

Calls: docs_search → docs_read. No API key needed — works offline.

Tips for Effective Prompts

Mention “Kelviq” early. LLMs typically have many MCP tools loaded. Saying “create a Kelviq customer” steers the model toward this server’s tools instead of guessing.
Use docs_search for fuzzy questions. When you’re unsure of an identifier or behaviour, ask the LLM to “search Kelviq docs” first — it grounds the follow-up calls in real semantics.
Trust the errors. Tools return {"error": {"status", "message"}} shapes for API errors. The LLM reads them and adjusts automatically (e.g. “Invalid product identifier” → asks you for the right one).
Combine tools in one prompt. The LLM is happy to chain calls. “Create the product, then publish all its plans” is one prompt, not five.

Troubleshooting

`Executable not found in $PATH: "node"` in Claude Code

GUI/launcher processes don’t source ~/.zshrc, so nvm’s node isn’t visible to them. Pick one fix:

Symlink node into a system path (recommended):
sudo ln -s "$(which node)" /usr/local/bin/node
One-time fix for every MCP server you’ll ever add.

Use the absolute node path:

claude mcp add kelviq \
  --env KELVIQ_SERVER_API_KEY=... \
  -- /Users/you/.nvm/versions/node/v20.19.0/bin/node \
     $(npm root -g)/@kelviq/mcp-server/dist/server.js

Install Node via Homebrew:
brew install node
Puts node on the system PATH so all GUI tools see it.

`error: unknown option '-y'` from `claude mcp add`

claude is intercepting -y as one of its own flags. Use -- to separate Claude’s args from the actual command:

claude mcp add kelviq \
  --env KELVIQ_SERVER_API_KEY=... \
  -- npx -y @kelviq/mcp-server

Tool returns `{"error": {"status": "Configuration error", ...}}`

A required env var is missing. The error message names which one — set it in your client config and reconnect.

Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`

Your API key works but the identifier doesn’t exist on this account. Most common cause: your key is for production but the identifier exists only in staging (or vice versa). Check KELVIQ_BASE_URL.

Test Without an AI Client

Use the official MCP Inspector to browse and call tools directly from a browser:

KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
  npx -y @modelcontextprotocol/inspector \
  npx -y @kelviq/mcp-server

Source & Contributing

npm — @kelviq/mcp-server
GitHub — kelviq/kelviq-mcp-server
Issues — github.com/kelviq/kelviq-mcp-server/issues
License — MIT

The repo is the canonical reference for tool schemas, build process, and contribution guidelines. New Kelviq API endpoints are added by extending the hand-written Zod schemas in src/schemas/kelviq.ts and the per-domain files in src/tools/.

Need Help?

Email us at hi@kelviq.com
Book a demo

Get Started

Quickstart

Product Catalog

Promotions

Checkout

Sales

Coustomers-management

Payouts

Customer-portal

Guides

Legal

How It Works

Step 1: Get Your API Keys

Step 2: Add the Server to Your AI Client

Step 3: Try It

Environment Variables

Point at Staging

Tool Reference

Customers

Checkout & Portal

Subscriptions

Entitlements, Licenses, Usage

Offerings & Promotions

Catalog: Products

Catalog: Features

Catalog: Plans

Docs (no API key required)

Resources

Built-in Prompts

Example Prompts

Tips for Effective Prompts

Troubleshooting

`Executable not found in $PATH: "node"` in Claude Code

`error: unknown option '-y'` from `claude mcp add`

Tool returns `{"error": {"status": "Configuration error", ...}}`

Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`

Test Without an AI Client

Source & Contributing

Need Help?

​How It Works

​Step 1: Get Your API Keys

​Step 2: Add the Server to Your AI Client

​Step 3: Try It

​Environment Variables

​Point at Staging

​Tool Reference

​Customers

​Checkout & Portal

​Subscriptions

​Entitlements, Licenses, Usage

​Offerings & Promotions

​Catalog: Products

​Catalog: Features

​Catalog: Plans

​Docs (no API key required)

​Resources

​Built-in Prompts

​Example Prompts

​Tips for Effective Prompts

​Troubleshooting

​Executable not found in $PATH: "node" in Claude Code

​error: unknown option '-y' from claude mcp add

​Tool returns {"error": {"status": "Configuration error", ...}}

​Tool returns {"error": {"status": "Bad request", "message": "Invalid product identifier"}}

​Test Without an AI Client

​Source & Contributing

​Need Help?

How It Works

Step 1: Get Your API Keys

Step 2: Add the Server to Your AI Client

Step 3: Try It

Environment Variables

Point at Staging

Tool Reference

Customers

Checkout & Portal

Subscriptions

Entitlements, Licenses, Usage

Offerings & Promotions

Catalog: Products

Catalog: Features

Catalog: Plans

Docs (no API key required)

Resources

Built-in Prompts

Example Prompts

Tips for Effective Prompts

Troubleshooting

`Executable not found in $PATH: "node"` in Claude Code

`error: unknown option '-y'` from `claude mcp add`

Tool returns `{"error": {"status": "Configuration error", ...}}`

Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`

Test Without an AI Client

Source & Contributing

Need Help?