@kelviq/mcp-server 0.2.3 → 0.3.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 (42) hide show
  1. package/README.md +21 -17
  2. package/dist/config.d.ts +8 -1
  3. package/dist/config.js +37 -6
  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/node-sdk.md +153 -0
  12. package/dist/docs/changelog/python-sdk.md +182 -0
  13. package/dist/docs/cli/commands.md +225 -0
  14. package/dist/docs/cli/environments.md +95 -0
  15. package/dist/docs/cli/kelviq-config.md +141 -0
  16. package/dist/docs/cli/overview.md +223 -0
  17. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  18. package/dist/docs/guides/mcp-server.md +129 -173
  19. package/dist/docs/guides/sandbox.md +107 -0
  20. package/dist/docs/guides/webhooks.md +81 -0
  21. package/dist/docs/manifest.json +57 -8
  22. package/dist/docs/openapi.json +1206 -50
  23. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  24. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  25. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  26. package/dist/schemas/kelviq.d.ts +0 -128
  27. package/dist/schemas/kelviq.js +0 -63
  28. package/dist/schemas/kelviq.js.map +1 -1
  29. package/dist/tools/index.js +0 -4
  30. package/dist/tools/index.js.map +1 -1
  31. package/dist/tools/plan-files.js +1 -1
  32. package/dist/tools/plan-files.js.map +1 -1
  33. package/dist/tools/plans.js +1 -15
  34. package/dist/tools/plans.js.map +1 -1
  35. package/dist/tools/portal.d.ts +11 -1
  36. package/dist/tools/portal.js +27 -2
  37. package/dist/tools/portal.js.map +1 -1
  38. package/dist/tools/products.js +1 -1
  39. package/dist/tools/products.js.map +1 -1
  40. package/dist/tools/subscriptions.js +1 -1
  41. package/dist/tools/subscriptions.js.map +1 -1
  42. package/package.json +5 -2
@@ -6,136 +6,126 @@ 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
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
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.
14
-
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**.
36
-
37
-
38
-
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
-
29
+ ## Step 1: Get Your API Keys
41
30
 
42
-
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.
43
36
 
44
-
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.
45
38
 
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, 51 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
- |---|---|---|---|
118
+ |----------|----------|---------|---------|
129
119
  | `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Bearer token for `api.kelviq.com` |
130
120
  | `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Bearer token for the edge host |
131
121
  | `KELVIQ_BASE_URL` | No | `https://api.kelviq.com/api/v1` | Override for sandbox / self-host |
132
122
  | `KELVIQ_EDGE_URL` | No | `https://edge.api.kelviq.com/api/v1` | Override the edge host (entitlements + promotions) |
133
123
 
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.
124
+ 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
125
 
136
- ### Point at staging
126
+ ### Point at Staging
137
127
 
138
- ```
128
+ ```env
139
129
  KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
140
130
  KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
141
131
  ```
@@ -151,21 +141,21 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
151
141
  ### Customers
152
142
 
153
143
  | Tool | Description |
154
- |---|---|
144
+ |------|-------------|
155
145
  | `customer_create` | Create a customer. Required: `customerId`. Optional: `email`, `name`, `metadata`, `billingAddress`. |
156
146
  | `customer_update` | Patch an existing customer by `customerId`. Only fields you pass are updated. |
157
147
 
158
148
  ### Checkout & Portal
159
149
 
160
150
  | Tool | Description |
161
- |---|---|
151
+ |------|-------------|
162
152
  | `checkout_create_session` | Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`. |
163
153
  | `portal_session_create` | Mint a pre-authenticated customer portal URL. |
164
154
 
165
155
  ### Subscriptions
166
156
 
167
157
  | Tool | Description |
168
- |---|---|
158
+ |------|-------------|
169
159
  | `subscription_create` | Create a subscription directly (skip checkout). |
170
160
  | `subscription_list` | List subscriptions, filter by customer, paginated. |
171
161
  | `subscription_update` | Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade. |
@@ -174,7 +164,7 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
174
164
  ### Entitlements, Licenses, Usage
175
165
 
176
166
  | Tool | Description |
177
- |---|---|
167
+ |------|-------------|
178
168
  | `entitlements_get` | Fetch entitlements for a customer. Pass `featureId` to scope. |
179
169
  | `license_activate` | Activate a license key for a specific instance. Returns `instanceId`. |
180
170
  | `license_deactivate` | Deactivate a license instance. |
@@ -184,14 +174,14 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
184
174
  ### Offerings & Promotions
185
175
 
186
176
  | Tool | Description |
187
- |---|---|
177
+ |------|-------------|
188
178
  | `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. |
179
+ | `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
190
180
 
191
181
  ### Catalog: Products
192
182
 
193
183
  | Tool | Description |
194
- |---|---|
184
+ |------|-------------|
195
185
  | `product_list` | List catalog products. Optional `search` substring + `page`. |
196
186
  | `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` from `media_presigned_upload`. |
197
187
  | `product_retrieve` | Fetch one product by UUID or identifier. |
@@ -205,7 +195,7 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
205
195
  ### Catalog: Features
206
196
 
207
197
  | Tool | Description |
208
- |---|---|
198
+ |------|-------------|
209
199
  | `feature_list` | List catalog features. |
210
200
  | `feature_create` | Create a feature. Required: `name`, `featureType` (`BOOLEAN` / `CUSTOMIZABLE` / `METER`). |
211
201
  | `feature_retrieve` | Fetch one feature. |
@@ -213,10 +203,10 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
213
203
 
214
204
  ### Catalog: Plans
215
205
 
216
- Plans are versioned: updates create a draft, `plan_publish` releases it.
206
+ Plans are versioned. Updates create a draft; `plan_publish` releases it.
217
207
 
218
208
  | Tool | Description |
219
- |---|---|
209
+ |------|-------------|
220
210
  | `plan_list` | List all plans in the account. |
221
211
  | `plan_create` | Create a plan under a product. Plan starts in `DRAFT`. |
222
212
  | `plan_retrieve` | Fetch one plan. |
@@ -225,7 +215,7 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
225
215
  | `plan_publish` | Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers. |
226
216
  | `plan_discard_draft` | Drop the current draft, keep the published version. |
227
217
  | `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. |
218
+ | `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`. |
@@ -237,13 +227,13 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
237
227
  ### Media
238
228
 
239
229
  | Tool | Description |
240
- |---|---|
230
+ |------|-------------|
241
231
  | `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
232
 
243
233
  ### Partner
244
234
 
245
235
  | Tool | Description |
246
- |---|---|
236
+ |------|-------------|
247
237
  | `partner_org_provision` | Provision a Kelviq org under your partner account. Required: `externalId`, `email`. Optional `businessName`. |
248
238
  | `partner_org_list` | List orgs you've provisioned. Optional `externalId` filter. |
249
239
  | `partner_org_retrieve` | Fetch a partner org by its Kelviq identifier. |
@@ -252,7 +242,7 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
252
242
  ### Docs (no API key required)
253
243
 
254
244
  | Tool | Description |
255
- |---|---|
245
+ |------|-------------|
256
246
  | `docs_search` | Full-text search across the bundled Kelviq docs. Returns `{slug, title, snippet, score}`. |
257
247
  | `docs_read` | Fetch a full markdown doc by slug. |
258
248
 
@@ -263,7 +253,7 @@ Plans are versioned: updates create a draft, `plan_publish` releases it.
263
253
  Resources let your AI client pin pages into context. The server advertises three categories:
264
254
 
265
255
  | URI pattern | Content |
266
- |---|---|
256
+ |-------------|---------|
267
257
  | `kelviq://docs/{section}/{slug}` | Every conceptual page in the Kelviq docs (~59 pages) |
268
258
  | `kelviq://openapi.json` | The full OpenAPI 3.0 spec (49 operations, every schema) |
269
259
  | `kelviq://README` | Top-level Kelviq overview |
@@ -274,73 +264,40 @@ For exhaustive per-endpoint request/response shapes, the **OpenAPI spec is the s
274
264
 
275
265
  ## Example Prompts
276
266
 
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.*
282
-
283
- Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_prices_bulk_set` × 3 → `plan_publish` × 3.
284
-
285
-
286
-
267
+ Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
287
268
 
288
- > *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
269
+ > *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.*
289
270
 
290
- Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
291
-
271
+ Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_prices_bulk_set` × 3 → `plan_publish` × 3.
292
272
 
293
-
273
+ > *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
294
274
 
295
- > *Provision a Kelviq org for partner external ID `acme-99`, owner email `ops@acme.com`, business name "Acme Corp".*
275
+ Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
296
276
 
297
- Calls: `partner_org_provision`. Returns the new org's identifier + API keys.
298
-
277
+ > *Provision a Kelviq org for partner external ID `acme-99`, owner email `ops@acme.com`, business name "Acme Corp".*
299
278
 
300
-
279
+ Calls: `partner_org_provision`. Returns the new org's identifier + API keys.
301
280
 
302
- > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
281
+ > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
303
282
 
304
- Calls: `license_activate` → `license_validate`.
305
-
283
+ Calls: `license_activate` → `license_validate`.
306
284
 
307
-
285
+ > *Show me all subscriptions for customer `acme-42` and tell me which features they have access to.*
308
286
 
309
- > *Show me all subscriptions for customer `acme-42` and tell me which features they have access to.*
287
+ Calls: `subscription_list` → `entitlements_get`.
310
288
 
311
- Calls: `subscription_list` → `entitlements_get`.
312
-
289
+ > *How do digital downloads work in Kelviq? What's the file-size limit?*
313
290
 
314
-
315
-
316
- > *How do digital downloads work in Kelviq? What's the file-size limit?*
317
-
318
- Calls: `docs_search` → `docs_read`. No API key needed — works offline.
319
-
291
+ Calls: `docs_search` → `docs_read`. No API key needed — works offline.
320
292
 
321
293
  ---
322
294
 
323
295
  ## Tips for Effective Prompts
324
296
 
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
-
297
+ - **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.
298
+ - **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.
299
+ - **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).
300
+ - **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
301
 
345
302
  ---
346
303
 
@@ -348,35 +305,27 @@ The whole point of the MCP server is that you describe the outcome, not the API
348
305
 
349
306
  ### `Executable not found in $PATH: "node"` in Claude Code
350
307
 
351
- GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to them. Pick one:
308
+ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to them. Pick one fix:
352
309
 
353
-
310
+ 1. **Symlink node into a system path** (recommended):
311
+ ```bash
312
+ sudo ln -s "$(which node)" /usr/local/bin/node
313
+ ```
314
+ One-time fix for every MCP server you'll ever add.
354
315
 
355
- ```bash
356
- sudo ln -s "$(which node)" /usr/local/bin/node
357
- ```
316
+ 2. **Use the absolute node path:**
317
+ ```bash
318
+ claude mcp add kelviq \
319
+ --env KELVIQ_SERVER_API_KEY=... \
320
+ -- /Users/you/.nvm/versions/node/v20.19.0/bin/node \
321
+ $(npm root -g)/@kelviq/mcp-server/dist/server.js
322
+ ```
358
323
 
359
- One-time fix for every MCP server you'll ever add.
360
-
361
-
362
-
363
-
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
-
371
-
372
-
373
-
374
- ```bash
375
- brew install node
376
- ```
377
-
378
- Puts `node` on the system PATH so all GUI tools see it.
379
-
324
+ 3. **Install Node via Homebrew:**
325
+ ```bash
326
+ brew install node
327
+ ```
328
+ Puts `node` on the system PATH so all GUI tools see it.
380
329
 
381
330
  ### `error: unknown option '-y'` from `claude mcp add`
382
331
 
@@ -396,7 +345,7 @@ A required env var is missing. The error message names which one — set it in y
396
345
 
397
346
  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
347
 
399
- ### Test without an AI client
348
+ ### Test Without an AI Client
400
349
 
401
350
  Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to browse and call tools directly from a browser:
402
351
 
@@ -410,9 +359,16 @@ KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
410
359
 
411
360
  ## Source & Contributing
412
361
 
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
362
+ - **npm** — [`@kelviq/mcp-server`](https://www.npmjs.com/package/@kelviq/mcp-server)
363
+ - **GitHub** — [`kelviq/kelviq-mcp-server`](https://github.com/kelviq/kelviq-mcp-server)
364
+ - **Issues** — [github.com/kelviq/kelviq-mcp-server/issues](https://github.com/kelviq/kelviq-mcp-server/issues)
365
+ - **License** — MIT
366
+
367
+ 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/`.
368
+
369
+ ---
370
+
371
+ ## Need Help?
417
372
 
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/`.
373
+ - Email us at **hi@kelviq.com**
374
+ - [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.