@kelviq/mcp-server 0.3.0 → 1.0.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 +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +84 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +134 -63
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +109 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +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 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- 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/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 +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- 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 +5 -0
- 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 +5 -1
- 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 +1 -1
|
@@ -4,17 +4,19 @@ slug: "guides/mcp-server"
|
|
|
4
4
|
section: "guides"
|
|
5
5
|
description: "Control Kelviq from Claude, Cursor, and any AI assistant that speaks the Model Context Protocol."
|
|
6
6
|
---
|
|
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,
|
|
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, Windsurf, VS Code, Antigravity — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
|
|
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
|
+
**Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and* five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
|
|
12
|
+
|
|
13
|
+
**45 tools** spanning customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and 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.
|
|
12
14
|
|
|
13
15
|
---
|
|
14
16
|
|
|
15
17
|
## How It Works
|
|
16
18
|
|
|
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.
|
|
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@latest`, connects over stdio, and discovers the tools and resources advertised by the server.
|
|
18
20
|
|
|
19
21
|
When the LLM decides to call a Kelviq tool, the server:
|
|
20
22
|
|
|
@@ -40,22 +42,21 @@ Never commit API keys to version control or paste them into shared chats. Use yo
|
|
|
40
42
|
|
|
41
43
|
## Step 2: Add the Server to Your AI Client
|
|
42
44
|
|
|
43
|
-
|
|
45
|
+
Every client uses the same underlying command — `npx -y @kelviq/mcp-server@latest` — with your API keys and `KELVIQ_ENV` passed as environment variables. What differs is the config file location and, in a few cases, the root JSON key. Pick the tab for your client.
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
The server uses your **sandbox** environment unless `KELVIQ_ENV=production`. Use keys from the same environment — to work with live data, use production keys and set `KELVIQ_ENV=production`.
|
|
46
48
|
|
|
47
49
|
```bash
|
|
48
50
|
claude mcp add kelviq \
|
|
49
51
|
--env KELVIQ_SERVER_API_KEY=<your-server-key> \
|
|
50
52
|
--env KELVIQ_CLIENT_API_KEY=<your-client-key> \
|
|
51
|
-
--
|
|
53
|
+
--env KELVIQ_ENV=sandbox \
|
|
54
|
+
-- npx -y @kelviq/mcp-server@latest
|
|
52
55
|
```
|
|
53
56
|
|
|
54
57
|
The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
|
|
55
58
|
|
|
56
|
-
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected,
|
|
57
|
-
|
|
58
|
-
### Claude Desktop
|
|
59
|
+
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 45 tools`.
|
|
59
60
|
|
|
60
61
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
|
|
61
62
|
|
|
@@ -64,10 +65,11 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
|
|
|
64
65
|
"mcpServers": {
|
|
65
66
|
"kelviq": {
|
|
66
67
|
"command": "npx",
|
|
67
|
-
"args": ["-y", "@kelviq/mcp-server"],
|
|
68
|
+
"args": ["-y", "@kelviq/mcp-server@latest"],
|
|
68
69
|
"env": {
|
|
69
70
|
"KELVIQ_SERVER_API_KEY": "server-...",
|
|
70
|
-
"KELVIQ_CLIENT_API_KEY": "client-..."
|
|
71
|
+
"KELVIQ_CLIENT_API_KEY": "client-...",
|
|
72
|
+
"KELVIQ_ENV": "sandbox"
|
|
71
73
|
}
|
|
72
74
|
}
|
|
73
75
|
}
|
|
@@ -76,22 +78,101 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
|
|
|
76
78
|
|
|
77
79
|
Restart Claude Desktop — the hammer icon shows `kelviq` with all tools.
|
|
78
80
|
|
|
79
|
-
|
|
81
|
+
Open **Cursor Settings → Tools and MCP → Add new MCP server**, or edit `.cursor/mcp.json` (project) / `~/.cursor/mcp.json` (global) directly:
|
|
80
82
|
|
|
81
|
-
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"mcpServers": {
|
|
86
|
+
"kelviq": {
|
|
87
|
+
"command": "npx",
|
|
88
|
+
"args": ["-y", "@kelviq/mcp-server@latest"],
|
|
89
|
+
"env": {
|
|
90
|
+
"KELVIQ_SERVER_API_KEY": "server-...",
|
|
91
|
+
"KELVIQ_CLIENT_API_KEY": "client-...",
|
|
92
|
+
"KELVIQ_ENV": "sandbox"
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
```
|
|
82
98
|
|
|
83
|
-
|
|
84
|
-
|-------|-------|
|
|
85
|
-
| Command | `npx` |
|
|
86
|
-
| Args | `-y @kelviq/mcp-server` |
|
|
87
|
-
| Environment Variables | `KELVIQ_SERVER_API_KEY`, `KELVIQ_CLIENT_API_KEY` |
|
|
99
|
+
Project-level config overrides global config when a server of the same name exists in both.
|
|
88
100
|
|
|
89
|
-
|
|
101
|
+
As of June 2026, Windsurf was rebranded **Devin Desktop** by Cognition. Existing installs update automatically — same editor, new name. The MCP config location also changed with the rebrand:
|
|
102
|
+
- **Devin Desktop (current):** `%APPDATA%\devin\config.json` (Windows) — via **Settings → Devin Local → Configuration → MCP servers**
|
|
103
|
+
- **Legacy Windsurf installs:** `~/.codeium/windsurf/mcp_config.json`
|
|
104
|
+
|
|
105
|
+
Add Kelviq under the `mcpServers` key:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"mcpServers": {
|
|
110
|
+
"kelviq": {
|
|
111
|
+
"command": "npx",
|
|
112
|
+
"args": ["-y", "@kelviq/mcp-server@latest"],
|
|
113
|
+
"env": {
|
|
114
|
+
"KELVIQ_SERVER_API_KEY": "server-...",
|
|
115
|
+
"KELVIQ_CLIENT_API_KEY": "client-...",
|
|
116
|
+
"KELVIQ_ENV": "sandbox"
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Save, then refresh or restart the app — `kelviq` should appear under **MCP servers** in Settings, where you can enable it and toggle individual tools.
|
|
124
|
+
|
|
125
|
+
If your `config.json` isn't empty, check its existing top-level structure before pasting — merge `kelviq` alongside whatever's already there rather than overwriting the file.
|
|
126
|
+
|
|
127
|
+
Add a `.vscode/mcp.json` in your workspace, or run **"MCP: Open User Configuration"** from the Command Palette for a global `mcp.json`. VS Code uses `servers`, not `mcpServers`, as the root key:
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"servers": {
|
|
132
|
+
"kelviq": {
|
|
133
|
+
"command": "npx",
|
|
134
|
+
"args": ["-y", "@kelviq/mcp-server@latest"],
|
|
135
|
+
"env": {
|
|
136
|
+
"KELVIQ_SERVER_API_KEY": "server-...",
|
|
137
|
+
"KELVIQ_CLIENT_API_KEY": "client-...",
|
|
138
|
+
"KELVIQ_ENV": "sandbox"
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Save, then click the **Start** CodeLens above the `kelviq` entry (or reload the window) and confirm it under the tools icon in Copilot Chat's Agent mode.
|
|
146
|
+
|
|
147
|
+
Already have Kelviq configured in Cursor or Windsurf? Under **Settings → Chat → MCP → Discovery**, check the matching box (e.g. "Windsurf configurations") to auto-import that server instead of retyping it. You can also use the `inputs` array to be prompted for the keys instead of storing them in plaintext.
|
|
148
|
+
|
|
149
|
+
Open the "..." menu in the Agent panel → **MCP Servers** → **Manage MCP Servers** → **View raw config**. This opens `mcp_config.json` at:
|
|
150
|
+
|
|
151
|
+
- **Windows:** `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json`
|
|
152
|
+
- **macOS/Linux:** `~/.gemini/antigravity/mcp_config.json`
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"mcpServers": {
|
|
157
|
+
"kelviq": {
|
|
158
|
+
"command": "npx",
|
|
159
|
+
"args": ["-y", "@kelviq/mcp-server@latest"],
|
|
160
|
+
"env": {
|
|
161
|
+
"KELVIQ_SERVER_API_KEY": "server-...",
|
|
162
|
+
"KELVIQ_CLIENT_API_KEY": "client-...",
|
|
163
|
+
"KELVIQ_ENV": "sandbox"
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The Antigravity **CLI** (as opposed to the IDE) uses a separate config path: `~/.gemini/antigravity-cli/mcp_config.json`.
|
|
90
171
|
|
|
91
172
|
Any client supporting stdio MCP servers works. Point it at:
|
|
92
173
|
|
|
93
174
|
```bash
|
|
94
|
-
npx -y @kelviq/mcp-server
|
|
175
|
+
npx -y @kelviq/mcp-server@latest
|
|
95
176
|
```
|
|
96
177
|
|
|
97
178
|
with the env vars listed below.
|
|
@@ -116,22 +197,14 @@ Your AI client should pick the right tool, call it, and show the result inline.
|
|
|
116
197
|
|
|
117
198
|
| Variable | Required | Default | Purpose |
|
|
118
199
|
|----------|----------|---------|---------|
|
|
119
|
-
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Bearer token for
|
|
120
|
-
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Bearer token for the edge host |
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
200
|
+
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
|
|
201
|
+
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
|
|
202
|
+
| `KELVIQ_ENV` | No | `sandbox` | `sandbox` or `production`. Set to `production` to work with live data — switches both API hosts automatically. Use a key from the same environment: keys only work against their own environment. |
|
|
203
|
+
| `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
|
|
204
|
+
| `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
|
|
123
205
|
|
|
124
206
|
Docs tools (`docs_search`, `docs_read`) work with no API keys at all. Even without a key, the LLM can answer Kelviq questions from the bundled documentation.
|
|
125
207
|
|
|
126
|
-
### Point at Staging
|
|
127
|
-
|
|
128
|
-
```env
|
|
129
|
-
KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
|
|
130
|
-
KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Pair these with a **staging-scoped** Server API Key from your dashboard's staging environment.
|
|
134
|
-
|
|
135
208
|
---
|
|
136
209
|
|
|
137
210
|
## Tool Reference
|
|
@@ -150,13 +223,13 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
|
|
|
150
223
|
| Tool | Description |
|
|
151
224
|
|------|-------------|
|
|
152
225
|
| `checkout_create_session` | Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`. |
|
|
153
|
-
| `portal_session_create` |
|
|
226
|
+
| `portal_session_create` | Create a customer portal session. Share the returned `signedPortalUrl` with the customer — the bare `customerPortalUrl` does not authenticate on its own. |
|
|
154
227
|
|
|
155
228
|
### Subscriptions
|
|
156
229
|
|
|
157
230
|
| Tool | Description |
|
|
158
231
|
|------|-------------|
|
|
159
|
-
| `subscription_create` | Create a subscription directly (skip checkout). |
|
|
232
|
+
| `subscription_create` | Create a subscription directly (skip checkout). Requires off-session charging to be enabled for your organization — otherwise use `checkout_create_session`. |
|
|
160
233
|
| `subscription_list` | List subscriptions, filter by customer, paginated. |
|
|
161
234
|
| `subscription_update` | Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade. |
|
|
162
235
|
| `subscription_cancel` | Cancel `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, or `SPECIFIC_DATE`. |
|
|
@@ -183,7 +256,7 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
|
|
|
183
256
|
| Tool | Description |
|
|
184
257
|
|------|-------------|
|
|
185
258
|
| `product_list` | List catalog products. Optional `search` substring + `page`. |
|
|
186
|
-
| `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` from `
|
|
259
|
+
| `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` (S3 file keys from the `POST /media/` API endpoint). |
|
|
187
260
|
| `product_retrieve` | Fetch one product by UUID or identifier. |
|
|
188
261
|
| `product_update` | Patch a product. |
|
|
189
262
|
| `product_archive` | Archive (soft-delete) a product. |
|
|
@@ -215,7 +288,6 @@ Plans are versioned. Updates create a draft; `plan_publish` releases it.
|
|
|
215
288
|
| `plan_publish` | Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers. |
|
|
216
289
|
| `plan_discard_draft` | Drop the current draft, keep the published version. |
|
|
217
290
|
| `plan_prices_list` | List all prices configured on a plan. |
|
|
218
|
-
| `plan_prices_bulk_set` | Atomically replace all prices. Supports `FLAT` / `PACKAGE` / `TIERED` / `VOLUME` / `STAIRSTEP` models. |
|
|
219
291
|
| `plan_entitlements_list` | List feature entitlements on a plan. |
|
|
220
292
|
| `plan_entitlements_add` | Attach feature entitlements. |
|
|
221
293
|
| `plan_entitlement_update` | Patch a single entitlement's `details`. |
|
|
@@ -224,21 +296,6 @@ Plans are versioned. Updates create a draft; `plan_publish` releases it.
|
|
|
224
296
|
| `plan_file_delete` | Remove a file from a plan. |
|
|
225
297
|
| `plan_file_download` | Download URL/stream for a plan file (buyer-facing deliverables). |
|
|
226
298
|
|
|
227
|
-
### Media
|
|
228
|
-
|
|
229
|
-
| Tool | Description |
|
|
230
|
-
|------|-------------|
|
|
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`). |
|
|
232
|
-
|
|
233
|
-
### Partner
|
|
234
|
-
|
|
235
|
-
| Tool | Description |
|
|
236
|
-
|------|-------------|
|
|
237
|
-
| `partner_org_provision` | Provision a Kelviq org under your partner account. Required: `externalId`, `email`. Optional `businessName`. |
|
|
238
|
-
| `partner_org_list` | List orgs you've provisioned. Optional `externalId` filter. |
|
|
239
|
-
| `partner_org_retrieve` | Fetch a partner org by its Kelviq identifier. |
|
|
240
|
-
| `partner_org_retrieve_by_external_id` | Fetch a partner org by your partner-side ID. |
|
|
241
|
-
|
|
242
299
|
### Docs (no API key required)
|
|
243
300
|
|
|
244
301
|
| Tool | Description |
|
|
@@ -254,30 +311,36 @@ Resources let your AI client pin pages into context. The server advertises three
|
|
|
254
311
|
|
|
255
312
|
| URI pattern | Content |
|
|
256
313
|
|-------------|---------|
|
|
257
|
-
| `kelviq://docs/{section}/{slug}` | Every
|
|
258
|
-
| `kelviq://openapi.json` | The full OpenAPI 3.0 spec (
|
|
314
|
+
| `kelviq://docs/{section}/{slug}` | Every page in the Kelviq docs |
|
|
315
|
+
| `kelviq://openapi.json` | The full OpenAPI 3.0 spec (every operation and schema) |
|
|
259
316
|
| `kelviq://README` | Top-level Kelviq overview |
|
|
260
317
|
|
|
261
318
|
For exhaustive per-endpoint request/response shapes, the **OpenAPI spec is the source of truth**. Ask your assistant *"check the OpenAPI spec for createSubscription"* and it will read the resource directly.
|
|
262
319
|
|
|
263
320
|
---
|
|
264
321
|
|
|
322
|
+
## Built-in Prompts
|
|
323
|
+
|
|
324
|
+
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.
|
|
325
|
+
|
|
326
|
+
| Prompt | Arguments | What it guides |
|
|
327
|
+
|--------|-----------|----------------|
|
|
328
|
+
| `setup_product` | `productName?`, `planName?` | Full catalog bootstrap: product → features → plan → entitlements → publish → verify. |
|
|
329
|
+
| `launch_plan` | `productId?`, `planName?` | Add and publish a new plan on an existing product, reusing existing features. |
|
|
330
|
+
| `diagnose_customer` | `customerId` | Cross-check a customer's entitlements, subscriptions, and plan configuration; ends with concrete next actions. |
|
|
331
|
+
|
|
265
332
|
## Example Prompts
|
|
266
333
|
|
|
267
334
|
Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
|
|
268
335
|
|
|
269
|
-
> *Create a Kelviq product called "Notion Plus" with tax code `saas`, then create three plans (Free, Pro Monthly
|
|
336
|
+
> *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.*
|
|
270
337
|
|
|
271
|
-
Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `
|
|
338
|
+
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.
|
|
272
339
|
|
|
273
340
|
> *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
|
|
274
341
|
|
|
275
342
|
Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
|
|
276
343
|
|
|
277
|
-
> *Provision a Kelviq org for partner external ID `acme-99`, owner email `ops@acme.com`, business name "Acme Corp".*
|
|
278
|
-
|
|
279
|
-
Calls: `partner_org_provision`. Returns the new org's identifier + API keys.
|
|
280
|
-
|
|
281
344
|
> *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
|
|
282
345
|
|
|
283
346
|
Calls: `license_activate` → `license_validate`.
|
|
@@ -334,16 +397,24 @@ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to
|
|
|
334
397
|
```bash
|
|
335
398
|
claude mcp add kelviq \
|
|
336
399
|
--env KELVIQ_SERVER_API_KEY=... \
|
|
337
|
-
-- npx -y @kelviq/mcp-server
|
|
400
|
+
-- npx -y @kelviq/mcp-server@latest
|
|
338
401
|
```
|
|
339
402
|
|
|
340
403
|
### Tool returns `{"error": {"status": "Configuration error", ...}}`
|
|
341
404
|
|
|
342
405
|
A required env var is missing. The error message names which one — set it in your client config and reconnect.
|
|
343
406
|
|
|
407
|
+
### Tool returns HTTP 401 or 403
|
|
408
|
+
|
|
409
|
+
Almost always, the key belongs to the other environment: a sandbox key only works against sandbox, and a production key only against production.
|
|
410
|
+
|
|
411
|
+
- The server uses sandbox unless `KELVIQ_ENV=production`. If your key is a production key, add `KELVIQ_ENV=production` to the server's environment and reconnect.
|
|
412
|
+
- The error message includes a hint naming the environment the server is using, and the startup log shows it too (`kelviq-mcp ready (env=…`). Make sure it matches your key.
|
|
413
|
+
- If neither shows an environment, your client is running an outdated copy of the server. Use `npx -y @kelviq/mcp-server@latest` in your client config.
|
|
414
|
+
|
|
344
415
|
### Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
|
|
345
416
|
|
|
346
|
-
Your API key works but the identifier doesn't exist on this account. Most common cause:
|
|
417
|
+
Your API key works but the identifier doesn't exist on this account. Most common cause: the identifier exists in the other environment — sandbox and production have separate catalogs. Check `KELVIQ_ENV`.
|
|
347
418
|
|
|
348
419
|
### Test Without an AI Client
|
|
349
420
|
|
|
@@ -352,7 +423,7 @@ Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspect
|
|
|
352
423
|
```bash
|
|
353
424
|
KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
|
|
354
425
|
npx -y @modelcontextprotocol/inspector \
|
|
355
|
-
npx -y @kelviq/mcp-server
|
|
426
|
+
npx -y @kelviq/mcp-server@latest
|
|
356
427
|
```
|
|
357
428
|
|
|
358
429
|
---
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Migrate from Cashfree"
|
|
3
|
+
slug: "guides/migrate-from-cashfree"
|
|
4
|
+
section: "guides"
|
|
5
|
+
description: "Get help moving from Cashfree to Kelviq"
|
|
6
|
+
---
|
|
7
|
+
Need help moving from Cashfree to Kelviq? Contact [hi@kelviq.com](mailto:hi@kelviq.com) to discuss your current setup.
|
|
@@ -94,6 +94,40 @@ Do not enter a real card number in the sandbox.
|
|
|
94
94
|
|
|
95
95
|
After payment, confirm that the test order, customer, subscription, and entitlements have the expected state in Sandbox mode.
|
|
96
96
|
|
|
97
|
+
## Test a subscription renewal
|
|
98
|
+
|
|
99
|
+
Daily billing is not enabled by default. Any sandbox organization can request it by contacting [Kelviq support](mailto:hi@kelviq.com).
|
|
100
|
+
|
|
101
|
+
After Daily billing is enabled, use it to test a renewal without waiting for a monthly or yearly billing cycle.
|
|
102
|
+
|
|
103
|
+
1. Enter Sandbox mode in the Kelviq dashboard.
|
|
104
|
+
2. Open the test plan you want to use.
|
|
105
|
+
3. Under **Billing cycles**, select **Daily** and enter a test price.
|
|
106
|
+
4. Publish the plan.
|
|
107
|
+
5. Start a subscription with a sandbox test card.
|
|
108
|
+
6. After the next billing cycle, check the order, invoice, subscription status, and entitlements in Sandbox mode.
|
|
109
|
+
|
|
110
|
+
If you create the checkout session through the API, set `chargePeriod` to `DAILY`:
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"planIdentifier": "sandbox-renewal-test",
|
|
115
|
+
"chargePeriod": "DAILY",
|
|
116
|
+
"customerId": "test-customer-001",
|
|
117
|
+
"successUrl": "https://example.com/billing/success"
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Can I test production with my own card?
|
|
122
|
+
|
|
123
|
+
No. Do not place a live order using your own card just to test production credentials. Payment providers can treat a self-payment as suspicious and block the card, even when the amount is small. There is no safe minimum price for this test.
|
|
124
|
+
|
|
125
|
+
Use one of these options instead:
|
|
126
|
+
|
|
127
|
+
* Keep payment and renewal testing in Sandbox.
|
|
128
|
+
* If you need to inspect the production checkout, [create a 100% discount code](/product-catalog/discounts) so no real payment is collected.
|
|
129
|
+
* Check production credentials, URLs, and environment settings without completing a purchase.
|
|
130
|
+
|
|
97
131
|
## Prepare for production
|
|
98
132
|
|
|
99
133
|
Before accepting live payments:
|
|
@@ -30,21 +30,32 @@ Add these to your `.env.local` file:
|
|
|
30
30
|
|
|
31
31
|
```env
|
|
32
32
|
# Backend (server-side only)
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
# API URLs
|
|
36
|
-
KELVIQ_API_BASE_URL=https://api.kelviq.com/api/v1
|
|
33
|
+
KELVIQ_SERVER_API_KEY=server-xxxxxxxx
|
|
34
|
+
KELVIQ_ENV=sandbox
|
|
37
35
|
|
|
38
36
|
# Frontend (can be exposed to client)
|
|
39
|
-
|
|
40
|
-
|
|
37
|
+
NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY=client-xxxxxxxx
|
|
38
|
+
NEXT_PUBLIC_KELVIQ_ENV=sandbox
|
|
41
39
|
|
|
42
40
|
# Your app URL (for redirects)
|
|
43
41
|
NEXT_PUBLIC_APP_URL=https://yourdomain.com
|
|
44
42
|
```
|
|
45
43
|
|
|
44
|
+
Build with sandbox keys — keys only work against their own environment. When you go live, switch both keys to production keys and set both `KELVIQ_ENV` values to `production`.
|
|
45
|
+
|
|
46
46
|
Never expose your server API key to the frontend or commit it to version control.
|
|
47
47
|
|
|
48
|
+
### Point API Routes at the Right Environment
|
|
49
|
+
|
|
50
|
+
Create `lib/kelviq.ts` so every API route calls the host that matches `KELVIQ_ENV`:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
export const KELVIQ_API_URL =
|
|
54
|
+
process.env.KELVIQ_ENV === "production"
|
|
55
|
+
? "https://api.kelviq.com/api/v1"
|
|
56
|
+
: "https://sandboxapi.kelviq.com/api/v1";
|
|
57
|
+
```
|
|
58
|
+
|
|
48
59
|
---
|
|
49
60
|
|
|
50
61
|
## Step 2: Define Your Plans
|
|
@@ -101,17 +112,18 @@ Create a customer record when a user signs up. This gives you more control and l
|
|
|
101
112
|
|
|
102
113
|
```typescript
|
|
103
114
|
import { NextRequest, NextResponse } from "next/server";
|
|
115
|
+
import { KELVIQ_API_URL } from "@/lib/kelviq";
|
|
104
116
|
|
|
105
117
|
export async function POST(request: NextRequest) {
|
|
106
118
|
const { customerId, name, email } = await request.json();
|
|
107
119
|
|
|
108
120
|
const response = await fetch(
|
|
109
|
-
`${
|
|
121
|
+
`${KELVIQ_API_URL}/customers/`,
|
|
110
122
|
{
|
|
111
123
|
method: "POST",
|
|
112
124
|
headers: {
|
|
113
125
|
"Content-Type": "application/json",
|
|
114
|
-
Authorization: `Bearer ${process.env.
|
|
126
|
+
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
|
|
115
127
|
},
|
|
116
128
|
body: JSON.stringify({ customerId, name, email }),
|
|
117
129
|
}
|
|
@@ -152,17 +164,18 @@ Create `app/api/checkout/route.ts`:
|
|
|
152
164
|
|
|
153
165
|
```typescript
|
|
154
166
|
import { NextRequest, NextResponse } from "next/server";
|
|
167
|
+
import { KELVIQ_API_URL } from "@/lib/kelviq";
|
|
155
168
|
|
|
156
169
|
export async function POST(request: NextRequest) {
|
|
157
170
|
const { planIdentifier, customerId, chargePeriod } = await request.json();
|
|
158
171
|
|
|
159
172
|
const response = await fetch(
|
|
160
|
-
`${
|
|
173
|
+
`${KELVIQ_API_URL}/checkout/`,
|
|
161
174
|
{
|
|
162
175
|
method: "POST",
|
|
163
176
|
headers: {
|
|
164
177
|
"Content-Type": "application/json",
|
|
165
|
-
Authorization: `Bearer ${process.env.
|
|
178
|
+
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
|
|
166
179
|
},
|
|
167
180
|
body: JSON.stringify({
|
|
168
181
|
planIdentifier,
|
|
@@ -246,15 +259,16 @@ Create `app/api/subscriptions/route.ts`:
|
|
|
246
259
|
|
|
247
260
|
```typescript
|
|
248
261
|
import { NextRequest, NextResponse } from "next/server";
|
|
262
|
+
import { KELVIQ_API_URL } from "@/lib/kelviq";
|
|
249
263
|
|
|
250
264
|
export async function GET(request: NextRequest) {
|
|
251
265
|
const customerId = request.nextUrl.searchParams.get("customerId");
|
|
252
266
|
|
|
253
267
|
const response = await fetch(
|
|
254
|
-
`${
|
|
268
|
+
`${KELVIQ_API_URL}/subscriptions/?customer_id=${customerId}`,
|
|
255
269
|
{
|
|
256
270
|
headers: {
|
|
257
|
-
Authorization: `Bearer ${process.env.
|
|
271
|
+
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
|
|
258
272
|
},
|
|
259
273
|
}
|
|
260
274
|
);
|
|
@@ -270,21 +284,28 @@ Create `app/api/subscriptions/update/route.ts`:
|
|
|
270
284
|
|
|
271
285
|
```typescript
|
|
272
286
|
import { NextRequest, NextResponse } from "next/server";
|
|
287
|
+
import { KELVIQ_API_URL } from "@/lib/kelviq";
|
|
273
288
|
|
|
274
289
|
export async function POST(request: NextRequest) {
|
|
275
|
-
const {
|
|
290
|
+
const {
|
|
291
|
+
subscriptionId,
|
|
292
|
+
planIdentifier,
|
|
293
|
+
chargePeriod,
|
|
294
|
+
paymentBehavior,
|
|
295
|
+
} = await request.json();
|
|
276
296
|
|
|
277
297
|
const response = await fetch(
|
|
278
|
-
`${
|
|
298
|
+
`${KELVIQ_API_URL}/subscriptions/${subscriptionId}/update/`,
|
|
279
299
|
{
|
|
280
300
|
method: "POST",
|
|
281
301
|
headers: {
|
|
282
302
|
"Content-Type": "application/json",
|
|
283
|
-
Authorization: `Bearer ${process.env.
|
|
303
|
+
Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
|
|
284
304
|
},
|
|
285
305
|
body: JSON.stringify({
|
|
286
306
|
planIdentifier,
|
|
287
307
|
chargePeriod: chargePeriod || "MONTHLY",
|
|
308
|
+
paymentBehavior,
|
|
288
309
|
}),
|
|
289
310
|
}
|
|
290
311
|
);
|
|
@@ -312,16 +333,21 @@ async function handlePlanChange(newPlanId: string) {
|
|
|
312
333
|
subscriptionId: current.id,
|
|
313
334
|
planIdentifier: newPlanId,
|
|
314
335
|
chargePeriod: "MONTHLY",
|
|
336
|
+
paymentBehavior: "activate_on_payment",
|
|
315
337
|
}),
|
|
316
338
|
});
|
|
317
339
|
|
|
318
|
-
alert("Plan
|
|
340
|
+
alert("Plan change started. The new plan becomes active after payment succeeds.");
|
|
319
341
|
} else {
|
|
320
342
|
// No subscription, redirect to checkout
|
|
321
343
|
}
|
|
322
344
|
}
|
|
323
345
|
```
|
|
324
346
|
|
|
347
|
+
With `activate_on_payment`, the existing subscription remains `active` while payment is pending. If the payment method requires UPI approval or 3DS authentication, the updated subscription starts as `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription stays active.
|
|
348
|
+
|
|
349
|
+
Do not unlock the new plan immediately after this route returns. Check the updated subscription status or fetch the customer's current entitlements first.
|
|
350
|
+
|
|
325
351
|
---
|
|
326
352
|
|
|
327
353
|
## Step 7: Gate Features with Entitlements
|
|
@@ -341,8 +367,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
|
|
|
341
367
|
<body>
|
|
342
368
|
<KelviqProvider
|
|
343
369
|
customerId={getCurrentUserId()}
|
|
344
|
-
accessToken={process.env.
|
|
345
|
-
|
|
370
|
+
accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY!}
|
|
371
|
+
environment={process.env.NEXT_PUBLIC_KELVIQ_ENV === "production" ? "production" : "sandbox"}
|
|
346
372
|
>
|
|
347
373
|
{children}
|
|
348
374
|
</KelviqProvider>
|
|
@@ -95,7 +95,7 @@ Redirect user to `checkoutUrl` → They complete payment → Redirected back to
|
|
|
95
95
|
| Parameter | Description |
|
|
96
96
|
|-----------|-------------|
|
|
97
97
|
| `planIdentifier` | The identifier of the plan (e.g., `"pro"`, `"enterprise"`) |
|
|
98
|
-
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
|
|
98
|
+
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"TWENTY_EIGHT_DAYS"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
|
|
99
99
|
| `successUrl` | URL to redirect after successful payment |
|
|
100
100
|
|
|
101
101
|
### Optional Parameters
|
|
@@ -155,6 +155,8 @@ const activeSubscription = results.find(s => s.status === "active");
|
|
|
155
155
|
}
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
+
Kelviq handles failed card payment retries and emails the customer a link to pay. Your application does not need its own retry process or payment recovery screen. See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments).
|
|
159
|
+
|
|
158
160
|
---
|
|
159
161
|
|
|
160
162
|
## Step 4: Update Subscription
|
|
@@ -174,7 +176,8 @@ const response = await fetch(
|
|
|
174
176
|
},
|
|
175
177
|
body: JSON.stringify({
|
|
176
178
|
planIdentifier: "enterprise",
|
|
177
|
-
chargePeriod: "MONTHLY"
|
|
179
|
+
chargePeriod: "MONTHLY",
|
|
180
|
+
paymentBehavior: "activate_on_payment"
|
|
178
181
|
})
|
|
179
182
|
}
|
|
180
183
|
);
|
|
@@ -197,6 +200,25 @@ const data = await response.json();
|
|
|
197
200
|
| `planIdentifier` | The identifier of the new plan |
|
|
198
201
|
| `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, etc. |
|
|
199
202
|
|
|
203
|
+
### Optional Parameters
|
|
204
|
+
|
|
205
|
+
| Parameter | Description |
|
|
206
|
+
|-----------|-------------|
|
|
207
|
+
| `paymentBehavior` | Set to `"activate_on_payment"` to keep the current subscription active until payment for the change succeeds. Omit it to apply the update immediately. |
|
|
208
|
+
|
|
209
|
+
### Activation after payment
|
|
210
|
+
|
|
211
|
+
Use `activate_on_payment` when a plan change should not affect access until Kelviq has collected payment.
|
|
212
|
+
|
|
213
|
+
| Payment path | What happens |
|
|
214
|
+
| --- | --- |
|
|
215
|
+
| Saved card with no customer action | Kelviq processes the payment immediately. The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
|
|
216
|
+
| UPI, 3DS, or another method requiring customer action | The updated subscription starts as `incomplete`. The existing subscription stays `active` until payment succeeds. |
|
|
217
|
+
| Payment succeeds | The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
|
|
218
|
+
| The immediate charge fails, or payment is not completed before expiry | The updated subscription becomes `incomplete_expired`. The existing subscription remains `active`. |
|
|
219
|
+
|
|
220
|
+
Do not grant the new plan's entitlements just because the update request returned successfully. Confirm that the updated subscription is `active`, or read the customer's current entitlements.
|
|
221
|
+
|
|
200
222
|
---
|
|
201
223
|
|
|
202
224
|
## Step 5: Check Entitlements
|
|
@@ -277,8 +299,10 @@ Use your **Client API Key** for this endpoint, not your Server API Key.
|
|
|
277
299
|
→ Show/hide features based on access
|
|
278
300
|
|
|
279
301
|
4. User wants to upgrade
|
|
280
|
-
→ Update subscription
|
|
281
|
-
→
|
|
302
|
+
→ Update the subscription with paymentBehavior: "activate_on_payment"
|
|
303
|
+
→ Keep the existing subscription active while payment is pending
|
|
304
|
+
→ After payment succeeds, the new subscription becomes active
|
|
305
|
+
→ The previous subscription becomes superseded
|
|
282
306
|
```
|
|
283
307
|
|
|
284
308
|
---
|