@kelviq/mcp-server 0.2.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +26 -23
  2. package/dist/config.d.ts +9 -1
  3. package/dist/config.js +38 -7
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/api-reference/authentication.md +7 -3
  6. package/dist/docs/api-reference/introduction.md +143 -0
  7. package/dist/docs/backend-integration/node-sdk.md +148 -6
  8. package/dist/docs/backend-integration/python-sdk.md +195 -11
  9. package/dist/docs/changelog/api.md +119 -0
  10. package/dist/docs/changelog/app.md +693 -0
  11. package/dist/docs/changelog/mcp-server.md +61 -0
  12. package/dist/docs/changelog/node-sdk.md +153 -0
  13. package/dist/docs/changelog/python-sdk.md +182 -0
  14. package/dist/docs/cli/commands.md +225 -0
  15. package/dist/docs/cli/environments.md +95 -0
  16. package/dist/docs/cli/kelviq-config.md +141 -0
  17. package/dist/docs/cli/overview.md +223 -0
  18. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  19. package/dist/docs/guides/mcp-server.md +141 -194
  20. package/dist/docs/guides/sandbox.md +107 -0
  21. package/dist/docs/guides/webhooks.md +81 -0
  22. package/dist/docs/manifest.json +64 -8
  23. package/dist/docs/openapi.json +1206 -50
  24. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  25. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  26. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  27. package/dist/prompts/index.d.ts +2 -0
  28. package/dist/prompts/index.js +107 -0
  29. package/dist/prompts/index.js.map +1 -0
  30. package/dist/schemas/kelviq.d.ts +30 -128
  31. package/dist/schemas/kelviq.js +50 -63
  32. package/dist/schemas/kelviq.js.map +1 -1
  33. package/dist/server.js +5 -2
  34. package/dist/server.js.map +1 -1
  35. package/dist/tools/checkout.js +2 -1
  36. package/dist/tools/checkout.js.map +1 -1
  37. package/dist/tools/customers.js +2 -0
  38. package/dist/tools/customers.js.map +1 -1
  39. package/dist/tools/docs.js +2 -0
  40. package/dist/tools/docs.js.map +1 -1
  41. package/dist/tools/entitlements.js +1 -0
  42. package/dist/tools/entitlements.js.map +1 -1
  43. package/dist/tools/features.js +4 -0
  44. package/dist/tools/features.js.map +1 -1
  45. package/dist/tools/index.js +0 -4
  46. package/dist/tools/index.js.map +1 -1
  47. package/dist/tools/licenses.js +3 -0
  48. package/dist/tools/licenses.js.map +1 -1
  49. package/dist/tools/offerings.js +1 -0
  50. package/dist/tools/offerings.js.map +1 -1
  51. package/dist/tools/plan-entitlements.js +4 -0
  52. package/dist/tools/plan-entitlements.js.map +1 -1
  53. package/dist/tools/plan-files.js +4 -1
  54. package/dist/tools/plan-files.js.map +1 -1
  55. package/dist/tools/plans.js +9 -15
  56. package/dist/tools/plans.js.map +1 -1
  57. package/dist/tools/portal.d.ts +11 -1
  58. package/dist/tools/portal.js +28 -2
  59. package/dist/tools/portal.js.map +1 -1
  60. package/dist/tools/product-files.js +2 -0
  61. package/dist/tools/product-files.js.map +1 -1
  62. package/dist/tools/product-settings.js +2 -0
  63. package/dist/tools/product-settings.js.map +1 -1
  64. package/dist/tools/products.js +6 -1
  65. package/dist/tools/products.js.map +1 -1
  66. package/dist/tools/promotions.js +1 -0
  67. package/dist/tools/promotions.js.map +1 -1
  68. package/dist/tools/subscriptions.js +6 -2
  69. package/dist/tools/subscriptions.js.map +1 -1
  70. package/dist/tools/usage.js +1 -0
  71. package/dist/tools/usage.js.map +1 -1
  72. package/package.json +5 -2
@@ -6,136 +6,127 @@ description: "Control Kelviq from Claude, Cursor, and any AI assistant that spea
6
6
  ---
7
7
  `@kelviq/mcp-server` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Zed — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
8
8
 
9
- In other words: instead of asking an assistant to "write me a curl command," you tell it *"create a Pro plan under product X and publish it"* and it does the work in one turn.
9
+ 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.
10
10
 
11
- **51 tools across 13 domains** (customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, portal, catalog products, catalog plans, catalog features, partner organizations) plus **61 resources** including the full OpenAPI spec.
12
-
13
- The package is open-source ([github.com/kelviq/kelviq-mcp-server](https://github.com/kelviq/kelviq-mcp-server), MIT) and published as `@kelviq/mcp-server` on npm.
11
+ **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](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
14
12
 
15
13
  ---
16
14
 
17
15
  ## How It Works
18
16
 
19
- 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` (or `node dist/server.js`), connects over stdio, and discovers the tools and resources advertised by the server.
17
+ 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.
20
18
 
21
19
  When the LLM decides to call a Kelviq tool, the server:
22
20
 
23
- 1. Validates the LLM-provided arguments against a Zod schema derived from Kelviq's OpenAPI spec
24
- 2. Adds your API key as a Bearer token and sends the HTTPS request to the appropriate Kelviq host
25
- 3. Returns the JSON response (or a structured `{"error": {...}}` object) back to the LLM
21
+ 1. Validates the LLM-provided arguments against a Zod schema derived from Kelviq's OpenAPI spec.
22
+ 2. Adds your API key as a Bearer token and sends the HTTPS request to the appropriate Kelviq host.
23
+ 3. Returns the JSON response (or a structured `{"error": {...}}` object) back to the LLM.
26
24
 
27
- API errors come back as content, not exceptions — the LLM reads them and reacts (re-tries with a fix, asks you to clarify, etc).
25
+ API errors are returned as content, not exceptions — the LLM reads them and reacts (retries with a fix, asks you to clarify, etc).
28
26
 
29
27
  ---
30
28
 
31
- ## Quickstart
32
-
33
-
34
-
35
- Generate a **Server API Key** at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys). If you plan to use the `promotion_get` tool, also generate a **Client API Key**.
29
+ ## Step 1: Get Your API Keys
36
30
 
37
-
31
+ 1. Sign in at [app.kelviq.com](https://app.kelviq.com).
32
+ 2. Navigate to **Settings → API Keys**.
33
+ 3. Copy:
34
+ - **Server API Key** — required for all API tools.
35
+ - **Client API Key** — required only for the `promotion_get` tool.
38
36
 
39
- Never commit keys to git or paste them into shared chats. Use your MCP client's `env` configuration mechanism — most clients store them in their own credentials file.
40
-
37
+ 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.
41
38
 
42
-
43
-
44
-
45
-
46
- Pick the tab that matches your client:
39
+ ---
47
40
 
48
-
41
+ ## Step 2: Add the Server to Your AI Client
49
42
 
50
-
43
+ Pick the section that matches your client.
51
44
 
52
- ```bash
53
- claude mcp add kelviq \
54
- --env KELVIQ_SERVER_API_KEY=<your-server-key> \
55
- --env KELVIQ_CLIENT_API_KEY=<your-client-key> \
56
- -- npx -y @kelviq/mcp-server
57
- ```
45
+ ### Claude Code (CLI)
58
46
 
59
- The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
47
+ ```bash
48
+ claude mcp add kelviq \
49
+ --env KELVIQ_SERVER_API_KEY=<your-server-key> \
50
+ --env KELVIQ_CLIENT_API_KEY=<your-client-key> \
51
+ -- npx -y @kelviq/mcp-server
52
+ ```
60
53
 
61
- Verify with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 51 tools`.
62
-
54
+ The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
63
55
 
64
-
56
+ Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 45 tools`.
65
57
 
66
- Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS:
58
+ ### Claude Desktop
67
59
 
68
- ```json
69
- {
70
- "mcpServers": {
71
- "kelviq": {
72
- "command": "npx",
73
- "args": ["-y", "@kelviq/mcp-server"],
74
- "env": {
75
- "KELVIQ_SERVER_API_KEY": "server-...",
76
- "KELVIQ_CLIENT_API_KEY": "client-..."
77
- }
78
- }
79
- }
80
- }
81
- ```
60
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
82
61
 
83
- Restart Claude Desktop. The hammer icon shows `kelviq` with all tools.
84
-
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "kelviq": {
66
+ "command": "npx",
67
+ "args": ["-y", "@kelviq/mcp-server"],
68
+ "env": {
69
+ "KELVIQ_SERVER_API_KEY": "server-...",
70
+ "KELVIQ_CLIENT_API_KEY": "client-..."
71
+ }
72
+ }
73
+ }
74
+ }
75
+ ```
85
76
 
86
-
77
+ Restart Claude Desktop — the hammer icon shows `kelviq` with all tools.
87
78
 
88
- Open **Cursor Settings → MCP**, click **Add new MCP server**, and configure:
79
+ ### Cursor
89
80
 
90
- - **Command:** `npx`
91
- - **Args:** `-y @kelviq/mcp-server`
92
- - **Environment Variables:** `KELVIQ_SERVER_API_KEY`, `KELVIQ_CLIENT_API_KEY`
93
-
81
+ Open **Cursor Settings → MCP**, click **Add new MCP server**, and configure:
94
82
 
95
-
83
+ | Field | Value |
84
+ |-------|-------|
85
+ | Command | `npx` |
86
+ | Args | `-y @kelviq/mcp-server` |
87
+ | Environment Variables | `KELVIQ_SERVER_API_KEY`, `KELVIQ_CLIENT_API_KEY` |
96
88
 
97
- Any client supporting stdio MCP servers works. Point it at the command:
89
+ ### Other Clients
98
90
 
99
- ```bash
100
- npx -y @kelviq/mcp-server
101
- ```
91
+ Any client supporting stdio MCP servers works. Point it at:
102
92
 
103
- with the env vars listed in [Environment Variables](#environment-variables) below.
104
-
93
+ ```bash
94
+ npx -y @kelviq/mcp-server
95
+ ```
105
96
 
106
-
97
+ with the env vars listed below.
107
98
 
108
-
99
+ ---
109
100
 
110
-
101
+ ## Step 3: Try It
111
102
 
112
- In a new session, type a prompt like:
103
+ In a new session, type a prompt like:
113
104
 
114
- > *Search Kelviq docs for license keys.*
105
+ > *Search Kelviq docs for license keys.*
115
106
 
116
- or
107
+ or
117
108
 
118
- > *List my Kelviq products.*
109
+ > *List my Kelviq products.*
119
110
 
120
- 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 — check the snippet above.
121
-
111
+ 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.
122
112
 
123
113
  ---
124
114
 
125
115
  ## Environment Variables
126
116
 
127
117
  | Variable | Required | Default | Purpose |
128
- |---|---|---|---|
129
- | `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Bearer token for `api.kelviq.com` |
130
- | `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Bearer token for the edge host |
131
- | `KELVIQ_BASE_URL` | No | `https://api.kelviq.com/api/v1` | Override for sandbox / self-host |
132
- | `KELVIQ_EDGE_URL` | No | `https://edge.api.kelviq.com/api/v1` | Override the edge host (entitlements + promotions) |
118
+ |----------|----------|---------|---------|
119
+ | `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
120
+ | `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
121
+ | `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. |
122
+ | `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
123
+ | `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
133
124
 
134
- **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.
125
+ 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.
135
126
 
136
- ### Point at staging
127
+ ### Point at Staging
137
128
 
138
- ```
129
+ ```env
139
130
  KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
140
131
  KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
141
132
  ```
@@ -151,22 +142,22 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
151
142
  ### Customers
152
143
 
153
144
  | Tool | Description |
154
- |---|---|
145
+ |------|-------------|
155
146
  | `customer_create` | Create a customer. Required: `customerId`. Optional: `email`, `name`, `metadata`, `billingAddress`. |
156
147
  | `customer_update` | Patch an existing customer by `customerId`. Only fields you pass are updated. |
157
148
 
158
149
  ### Checkout & Portal
159
150
 
160
151
  | Tool | Description |
161
- |---|---|
152
+ |------|-------------|
162
153
  | `checkout_create_session` | Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`. |
163
- | `portal_session_create` | Mint a pre-authenticated customer portal URL. |
154
+ | `portal_session_create` | Create a customer portal session. Share the returned `signedPortalUrl` with the customer — the bare `customerPortalUrl` does not authenticate on its own. |
164
155
 
165
156
  ### Subscriptions
166
157
 
167
158
  | Tool | Description |
168
- |---|---|
169
- | `subscription_create` | Create a subscription directly (skip checkout). |
159
+ |------|-------------|
160
+ | `subscription_create` | Create a subscription directly (skip checkout). Requires off-session charging to be enabled for your organization — otherwise use `checkout_create_session`. |
170
161
  | `subscription_list` | List subscriptions, filter by customer, paginated. |
171
162
  | `subscription_update` | Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade. |
172
163
  | `subscription_cancel` | Cancel `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, or `SPECIFIC_DATE`. |
@@ -174,7 +165,7 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
174
165
  ### Entitlements, Licenses, Usage
175
166
 
176
167
  | Tool | Description |
177
- |---|---|
168
+ |------|-------------|
178
169
  | `entitlements_get` | Fetch entitlements for a customer. Pass `featureId` to scope. |
179
170
  | `license_activate` | Activate a license key for a specific instance. Returns `instanceId`. |
180
171
  | `license_deactivate` | Deactivate a license instance. |
@@ -184,16 +175,16 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
184
175
  ### Offerings & Promotions
185
176
 
186
177
  | Tool | Description |
187
- |---|---|
178
+ |------|-------------|
188
179
  | `offering_get_product` | Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state. |
189
- | `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key + edge host. |
180
+ | `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
190
181
 
191
182
  ### Catalog: Products
192
183
 
193
184
  | Tool | Description |
194
- |---|---|
185
+ |------|-------------|
195
186
  | `product_list` | List catalog products. Optional `search` substring + `page`. |
196
- | `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` from `media_presigned_upload`. |
187
+ | `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` (S3 file keys from the `POST /media/` API endpoint). |
197
188
  | `product_retrieve` | Fetch one product by UUID or identifier. |
198
189
  | `product_update` | Patch a product. |
199
190
  | `product_archive` | Archive (soft-delete) a product. |
@@ -205,7 +196,7 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
205
196
  ### Catalog: Features
206
197
 
207
198
  | Tool | Description |
208
- |---|---|
199
+ |------|-------------|
209
200
  | `feature_list` | List catalog features. |
210
201
  | `feature_create` | Create a feature. Required: `name`, `featureType` (`BOOLEAN` / `CUSTOMIZABLE` / `METER`). |
211
202
  | `feature_retrieve` | Fetch one feature. |
@@ -213,10 +204,10 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
213
204
 
214
205
  ### Catalog: Plans
215
206
 
216
- Plans are versioned: updates create a draft, `plan_publish` releases it.
207
+ Plans are versioned. Updates create a draft; `plan_publish` releases it.
217
208
 
218
209
  | Tool | Description |
219
- |---|---|
210
+ |------|-------------|
220
211
  | `plan_list` | List all plans in the account. |
221
212
  | `plan_create` | Create a plan under a product. Plan starts in `DRAFT`. |
222
213
  | `plan_retrieve` | Fetch one plan. |
@@ -225,7 +216,6 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
225
216
  | `plan_publish` | Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers. |
226
217
  | `plan_discard_draft` | Drop the current draft, keep the published version. |
227
218
  | `plan_prices_list` | List all prices configured on a plan. |
228
- | `plan_prices_bulk_set` | Atomically replace all prices. Supports FLAT / PACKAGE / TIERED / VOLUME / STAIRSTEP models. |
229
219
  | `plan_entitlements_list` | List feature entitlements on a plan. |
230
220
  | `plan_entitlements_add` | Attach feature entitlements. |
231
221
  | `plan_entitlement_update` | Patch a single entitlement's `details`. |
@@ -234,25 +224,10 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
234
224
  | `plan_file_delete` | Remove a file from a plan. |
235
225
  | `plan_file_download` | Download URL/stream for a plan file (buyer-facing deliverables). |
236
226
 
237
- ### Media
238
-
239
- | Tool | Description |
240
- |---|---|
241
- | `media_presigned_upload` | Get a presigned S3 POST policy (max 5 GB). Returns a `fileKey` to pass into `product_create`/`product_update` (`imageKeys`) or `plan_create`/`plan_update` (`fileKeys`). |
242
-
243
- ### Partner
244
-
245
- | Tool | Description |
246
- |---|---|
247
- | `partner_org_provision` | Provision a Kelviq org under your partner account. Required: `externalId`, `email`. Optional `businessName`. |
248
- | `partner_org_list` | List orgs you've provisioned. Optional `externalId` filter. |
249
- | `partner_org_retrieve` | Fetch a partner org by its Kelviq identifier. |
250
- | `partner_org_retrieve_by_external_id` | Fetch a partner org by your partner-side ID. |
251
-
252
227
  ### Docs (no API key required)
253
228
 
254
229
  | Tool | Description |
255
- |---|---|
230
+ |------|-------------|
256
231
  | `docs_search` | Full-text search across the bundled Kelviq docs. Returns `{slug, title, snippet, score}`. |
257
232
  | `docs_read` | Fetch a full markdown doc by slug. |
258
233
 
@@ -263,7 +238,7 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
263
238
  Resources let your AI client pin pages into context. The server advertises three categories:
264
239
 
265
240
  | URI pattern | Content |
266
- |---|---|
241
+ |-------------|---------|
267
242
  | `kelviq://docs/{section}/{slug}` | Every conceptual page in the Kelviq docs (~59 pages) |
268
243
  | `kelviq://openapi.json` | The full OpenAPI 3.0 spec (49 operations, every schema) |
269
244
  | `kelviq://README` | Top-level Kelviq overview |
@@ -272,75 +247,48 @@ For exhaustive per-endpoint request/response shapes, the **OpenAPI spec is the s
272
247
 
273
248
  ---
274
249
 
275
- ## Example Prompts
276
-
277
- The whole point of the MCP server is that you describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
278
-
279
-
280
-
281
- > *Create a Kelviq product called "Notion Plus" with tax code `saas`, then create three plans (Free, Pro Monthly $19, Pro Yearly $190), add an `api-calls` feature with limits 1000 / 50000 / unlimited, and publish all three plans.*
250
+ ## Built-in Prompts
282
251
 
283
- Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_prices_bulk_set` × 3 → `plan_publish` × 3.
284
-
252
+ 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](/cli/overview), 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.
285
253
 
286
-
254
+ | Prompt | Arguments | What it guides |
255
+ |--------|-----------|----------------|
256
+ | `setup_product` | `productName?`, `planName?` | Full catalog bootstrap: product → features → plan → entitlements → publish → verify. |
257
+ | `launch_plan` | `productId?`, `planName?` | Add and publish a new plan on an existing product, reusing existing features. |
258
+ | `diagnose_customer` | `customerId` | Cross-check a customer's entitlements, subscriptions, and plan configuration; ends with concrete next actions. |
287
259
 
288
- > *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
289
-
290
- Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
291
-
292
-
293
-
260
+ ## Example Prompts
294
261
 
295
- > *Provision a Kelviq org for partner external ID `acme-99`, owner email `ops@acme.com`, business name "Acme Corp".*
262
+ Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
296
263
 
297
- Calls: `partner_org_provision`. Returns the new org's identifier + API keys.
298
-
264
+ > *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.*
299
265
 
300
-
266
+ 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](https://app.kelviq.com) or with the [Kelviq CLI](/cli/overview), which manages pricing as reviewable code.
301
267
 
302
- > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
268
+ > *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
303
269
 
304
- Calls: `license_activate` → `license_validate`.
305
-
270
+ Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
306
271
 
307
-
272
+ > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
308
273
 
309
- > *Show me all subscriptions for customer `acme-42` and tell me which features they have access to.*
274
+ Calls: `license_activate` → `license_validate`.
310
275
 
311
- Calls: `subscription_list` → `entitlements_get`.
312
-
276
+ > *Show me all subscriptions for customer `acme-42` and tell me which features they have access to.*
313
277
 
314
-
278
+ Calls: `subscription_list` → `entitlements_get`.
315
279
 
316
- > *How do digital downloads work in Kelviq? What's the file-size limit?*
280
+ > *How do digital downloads work in Kelviq? What's the file-size limit?*
317
281
 
318
- Calls: `docs_search` → `docs_read`. No API key needed — works offline.
319
-
282
+ Calls: `docs_search` → `docs_read`. No API key needed — works offline.
320
283
 
321
284
  ---
322
285
 
323
286
  ## Tips for Effective Prompts
324
287
 
325
-
326
-
327
- LLMs typically have many MCP tools loaded. Saying "create a *Kelviq* customer" steers the model toward this server's tools instead of guessing.
328
-
329
-
330
-
331
-
332
- 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.
333
-
334
-
335
-
336
-
337
- Tools return `{"error": {"status", "message"}}` shapes for API errors. The LLM will read them and adjust automatically (e.g. "Invalid product identifier" → ask you for the right one).
338
-
339
-
340
-
341
-
342
- The LLM is happy to chain calls. "Create the product, then publish all its plans" is one prompt, not five.
343
-
288
+ - **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.
289
+ - **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.
290
+ - **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).
291
+ - **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.
344
292
 
345
293
  ---
346
294
 
@@ -348,35 +296,27 @@ The whole point of the MCP server is that you describe the outcome, not the API
348
296
 
349
297
  ### `Executable not found in $PATH: "node"` in Claude Code
350
298
 
351
- GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to them. Pick one:
352
-
353
-
354
-
355
- ```bash
356
- sudo ln -s "$(which node)" /usr/local/bin/node
357
- ```
358
-
359
- One-time fix for every MCP server you'll ever add.
360
-
361
-
362
-
299
+ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to them. Pick one fix:
363
300
 
364
- ```bash
365
- claude mcp add kelviq \
366
- --env KELVIQ_SERVER_API_KEY=... \
367
- -- /Users/you/.nvm/versions/node/v20.19.0/bin/node \
368
- $(npm root -g)/@kelviq/mcp-server/dist/server.js
369
- ```
370
-
301
+ 1. **Symlink node into a system path** (recommended):
302
+ ```bash
303
+ sudo ln -s "$(which node)" /usr/local/bin/node
304
+ ```
305
+ One-time fix for every MCP server you'll ever add.
371
306
 
372
-
307
+ 2. **Use the absolute node path:**
308
+ ```bash
309
+ claude mcp add kelviq \
310
+ --env KELVIQ_SERVER_API_KEY=... \
311
+ -- /Users/you/.nvm/versions/node/v20.19.0/bin/node \
312
+ $(npm root -g)/@kelviq/mcp-server/dist/server.js
313
+ ```
373
314
 
374
- ```bash
375
- brew install node
376
- ```
377
-
378
- Puts `node` on the system PATH so all GUI tools see it.
379
-
315
+ 3. **Install Node via Homebrew:**
316
+ ```bash
317
+ brew install node
318
+ ```
319
+ Puts `node` on the system PATH so all GUI tools see it.
380
320
 
381
321
  ### `error: unknown option '-y'` from `claude mcp add`
382
322
 
@@ -396,7 +336,7 @@ A required env var is missing. The error message names which one — set it in y
396
336
 
397
337
  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`.
398
338
 
399
- ### Test without an AI client
339
+ ### Test Without an AI Client
400
340
 
401
341
  Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to browse and call tools directly from a browser:
402
342
 
@@ -410,9 +350,16 @@ KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
410
350
 
411
351
  ## Source & Contributing
412
352
 
413
- - **npm:** [`@kelviq/mcp-server`](https://www.npmjs.com/package/@kelviq/mcp-server)
414
- - **GitHub:** [`kelviq/kelviq-mcp-server`](https://github.com/kelviq/kelviq-mcp-server)
415
- - **Issues:** [github.com/kelviq/kelviq-mcp-server/issues](https://github.com/kelviq/kelviq-mcp-server/issues)
416
- - **License:** MIT
353
+ - **npm** — [`@kelviq/mcp-server`](https://www.npmjs.com/package/@kelviq/mcp-server)
354
+ - **GitHub** — [`kelviq/kelviq-mcp-server`](https://github.com/kelviq/kelviq-mcp-server)
355
+ - **Issues** — [github.com/kelviq/kelviq-mcp-server/issues](https://github.com/kelviq/kelviq-mcp-server/issues)
356
+ - **License** — MIT
357
+
358
+ 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/`.
359
+
360
+ ---
361
+
362
+ ## Need Help?
417
363
 
418
- 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/`.
364
+ - Email us at **hi@kelviq.com**
365
+ - [Book a demo](https://tidycal.com/neravath/15-minute-meeting)
@@ -0,0 +1,107 @@
1
+ ---
2
+ title: "Sandbox"
3
+ slug: "guides/sandbox"
4
+ section: "guides"
5
+ description: "Build and test your Kelviq integration without affecting production data or processing real payments"
6
+ ---
7
+ Kelviq's sandbox is a separate environment for development and testing. You can configure products and plans, create customers, exercise checkout flows, and test your integration without affecting your live organization or processing real payments.
8
+
9
+ ## How isolation works
10
+
11
+ Sandbox and production use separate data and credentials.
12
+
13
+ | Resource | Sandbox behavior |
14
+ | --- | --- |
15
+ | Data | Products, plans, customers, subscriptions, and orders are isolated from production |
16
+ | API keys | Work only with sandbox hosts |
17
+ | Payments | Use test card details; no real charge is made |
18
+
19
+ This separation prevents development activity from changing live customer or billing data. Before launch, configure the resources your integration needs in production and replace all sandbox credentials and URLs.
20
+
21
+ ## Get started
22
+
23
+ 1. Sign in to the [Kelviq dashboard](https://app.kelviq.com).
24
+ 2. Open the organization dropdown and click **Enter sandbox**.
25
+ 3. Create the products, plans, prices, and other test data you need.
26
+ 4. Open **Settings → API keys** and copy the sandbox key required by your integration.
27
+
28
+ Never use a production Server API Key in test code. Store Server API Keys in environment variables and use Client API Keys only in supported browser integrations.
29
+
30
+ ## Connect to the sandbox API
31
+
32
+ Use the sandbox hosts with sandbox-scoped credentials:
33
+
34
+ | API | Sandbox base URL |
35
+ | --- | --- |
36
+ | Core API | `https://sandboxapi.kelviq.com/api/v1` |
37
+ | Edge API | `https://edge.sandboxapi.kelviq.com/api/v1` |
38
+
39
+ For example:
40
+
41
+ ```bash
42
+ curl https://sandboxapi.kelviq.com/api/v1/catalog/products/ \
43
+ --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
44
+ --header "Accept: application/json"
45
+ ```
46
+
47
+ Changing only the URL is not enough: the request must also use an API key created while the dashboard is in Sandbox mode.
48
+
49
+ ## Use the sandbox with an SDK
50
+
51
+ Set `environment` to `sandbox` when initializing an official SDK.
52
+
53
+ ```typescript Node.js
54
+ import { Kelviq } from "@kelviq/node-sdk";
55
+
56
+ const client = new Kelviq({
57
+ accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
58
+ environment: "sandbox",
59
+ });
60
+ ```
61
+
62
+ ```python Python
63
+ from kelviq_sdk import Kelviq
64
+
65
+ client = Kelviq.create_sync_client(
66
+ access_token=KELVIQ_SANDBOX_SERVER_API_KEY,
67
+ environment="sandbox",
68
+ )
69
+ ```
70
+
71
+ ```tsx React
72
+ <KelviqProvider
73
+ customerId="YOUR_TEST_CUSTOMER_ID"
74
+ accessToken="YOUR_SANDBOX_CLIENT_API_KEY"
75
+ environment="sandbox"
76
+ >
77
+ {children}
78
+ </KelviqProvider>
79
+ ```
80
+
81
+ See the [Node SDK](/backend-integration/node-sdk), [Python SDK](/backend-integration/python-sdk), or [frontend SDK guides](/frontend-integration/react-sdk) for full setup instructions.
82
+
83
+ ## Test checkout
84
+
85
+ Create a checkout in the sandbox and use Stripe test card details. Use any future expiration date and a valid test CVC.
86
+
87
+ | Card number | Result |
88
+ | --- | --- |
89
+ | `4242 4242 4242 4242` | Successful payment |
90
+ | `4000 0000 0000 0002` | Declined payment |
91
+ | `4000 0025 0000 3155` | Payment requiring authentication |
92
+
93
+ Do not enter a real card number in the sandbox.
94
+
95
+ After payment, confirm that the test order, customer, subscription, and entitlements have the expected state in Sandbox mode.
96
+
97
+ ## Prepare for production
98
+
99
+ Before accepting live payments:
100
+
101
+ 1. Complete the required [business review and payout setup](/getstarted/review-process).
102
+ 2. Configure and publish your production products and plans.
103
+ 3. Replace sandbox API keys with production API keys.
104
+ 4. Replace sandbox base URLs or set each SDK's environment to `production`.
105
+ 5. Run a final check that no sandbox credentials or hosts remain in your production configuration.
106
+
107
+ Use clearly named variables such as `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` to reduce the chance of mixing environments.