@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.
- package/README.md +21 -17
- package/dist/config.d.ts +8 -1
- package/dist/config.js +37 -6
- package/dist/config.js.map +1 -1
- package/dist/docs/api-reference/authentication.md +7 -3
- package/dist/docs/api-reference/introduction.md +143 -0
- package/dist/docs/backend-integration/node-sdk.md +148 -6
- package/dist/docs/backend-integration/python-sdk.md +195 -11
- package/dist/docs/changelog/api.md +119 -0
- package/dist/docs/changelog/app.md +693 -0
- package/dist/docs/changelog/node-sdk.md +153 -0
- package/dist/docs/changelog/python-sdk.md +182 -0
- package/dist/docs/cli/commands.md +225 -0
- package/dist/docs/cli/environments.md +95 -0
- package/dist/docs/cli/kelviq-config.md +141 -0
- package/dist/docs/cli/overview.md +223 -0
- package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
- package/dist/docs/guides/mcp-server.md +129 -173
- package/dist/docs/guides/sandbox.md +107 -0
- package/dist/docs/guides/webhooks.md +81 -0
- package/dist/docs/manifest.json +57 -8
- package/dist/docs/openapi.json +1206 -50
- package/dist/docs/product-catalog/one-time-payments.md +3 -1
- package/dist/docs/product-catalog/usage-based-billing.md +86 -7
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/schemas/kelviq.d.ts +0 -128
- package/dist/schemas/kelviq.js +0 -63
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/tools/index.js +0 -4
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/plan-files.js +1 -1
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +1 -15
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.d.ts +11 -1
- package/dist/tools/portal.js +27 -2
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/products.js +1 -1
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/subscriptions.js +1 -1
- package/dist/tools/subscriptions.js.map +1 -1
- 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
|
-
|
|
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
|
|
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
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
58
|
+
### Claude Desktop
|
|
67
59
|
|
|
68
|
-
|
|
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
|
-
|
|
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
|
-
|
|
79
|
+
### Cursor
|
|
89
80
|
|
|
90
|
-
|
|
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
|
-
|
|
89
|
+
### Other Clients
|
|
98
90
|
|
|
99
|
-
|
|
100
|
-
npx -y @kelviq/mcp-server
|
|
101
|
-
```
|
|
91
|
+
Any client supporting stdio MCP servers works. Point it at:
|
|
102
92
|
|
|
103
|
-
|
|
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
|
-
|
|
103
|
+
In a new session, type a prompt like:
|
|
113
104
|
|
|
114
|
-
|
|
105
|
+
> *Search Kelviq docs for license keys.*
|
|
115
106
|
|
|
116
|
-
|
|
107
|
+
or
|
|
117
108
|
|
|
118
|
-
|
|
109
|
+
> *List my Kelviq products.*
|
|
119
110
|
|
|
120
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
275
|
+
Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
|
|
296
276
|
|
|
297
|
-
|
|
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
|
-
|
|
281
|
+
> *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
|
|
303
282
|
|
|
304
|
-
|
|
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
|
-
|
|
287
|
+
Calls: `subscription_list` → `entitlements_get`.
|
|
310
288
|
|
|
311
|
-
|
|
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
|
-
|
|
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
|
-
|
|
356
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
414
|
-
- **GitHub
|
|
415
|
-
- **Issues
|
|
416
|
-
- **License
|
|
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
|
-
|
|
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.
|