@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.
- package/README.md +26 -23
- package/dist/config.d.ts +9 -1
- package/dist/config.js +38 -7
- 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/mcp-server.md +61 -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 +141 -194
- package/dist/docs/guides/sandbox.md +107 -0
- package/dist/docs/guides/webhooks.md +81 -0
- package/dist/docs/manifest.json +64 -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/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -128
- package/dist/schemas/kelviq.js +50 -63
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +5 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/index.js +0 -4
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +4 -1
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +9 -15
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.d.ts +11 -1
- package/dist/tools/portal.js +28 -2
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +6 -1
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +6 -2
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- 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
|
-
|
|
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
|
-
**
|
|
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
|
|
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**.
|
|
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
|
-
|
|
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
|
-
|
|
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, 45 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
|
-
|
|
129
|
-
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Bearer token for
|
|
130
|
-
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Bearer token for the edge host |
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
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
|
-
|
|
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
|
|
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` |
|
|
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
|
|
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 `
|
|
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
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
289
|
-
|
|
290
|
-
Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
260
|
+
## Example Prompts
|
|
294
261
|
|
|
295
|
-
|
|
262
|
+
Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
|
|
296
263
|
|
|
297
|
-
|
|
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
|
-
|
|
268
|
+
> *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
|
|
303
269
|
|
|
304
|
-
|
|
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
|
-
|
|
274
|
+
Calls: `license_activate` → `license_validate`.
|
|
310
275
|
|
|
311
|
-
|
|
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
|
-
|
|
280
|
+
> *How do digital downloads work in Kelviq? What's the file-size limit?*
|
|
317
281
|
|
|
318
|
-
|
|
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
|
-
|
|
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
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
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
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
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
|
|
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
|
|
414
|
-
- **GitHub
|
|
415
|
-
- **Issues
|
|
416
|
-
- **License
|
|
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
|
-
|
|
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.
|