@kelviq/mcp-server 0.4.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 +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- 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 +23 -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 +114 -34
- 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 +102 -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/server.js +10 -1
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Payment security and seller funds"
|
|
3
|
+
slug: "getstarted/payment-security-and-seller-funds"
|
|
4
|
+
section: "getstarted"
|
|
5
|
+
description: "How Kelviq protects card details, routes payments through Stripe, and handles payouts, account reviews, and migrations"
|
|
6
|
+
---
|
|
7
|
+
When a customer buys through Kelviq Checkout, Kelviq is the Merchant of Record and Stripe processes the payment. The customer's raw card details go directly to Stripe through secure payment fields; they are not passed to Kelviq or your connected account. Stripe also provides the connected account used for your payouts. Here is how payment data, money, and subscription records move at each stage.
|
|
8
|
+
|
|
9
|
+
This page is an operational overview. If it conflicts with the [Seller Agreement](/legal/master-service-agreement), the agreement controls.
|
|
10
|
+
|
|
11
|
+
## How does a payment move?
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
Kelviq Checkout uses [Stripe Elements](https://docs.stripe.com/payments/elements). Stripe tokenizes sensitive payment details in the browser, so the full card number and CVC do not pass through or get stored on Kelviq's servers.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
The charge and its PaymentIntent are created on Kelviq's Stripe platform account because Kelviq is the Merchant of Record.
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
Kelviq accounts for applicable taxes, platform fees, refunds, and other adjustments before calculating your net revenue.
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
Kelviq creates a separate transfer to your Stripe Express connected account. The funds appear there after Stripe makes them available.
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
You can withdraw cleared funds to the bank account attached to your connected account.
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
Kelviq uses Stripe Connect's **separate charges and transfers** model. It does not use direct charges or destination charges. See the [full payment flow](/legal/payment-flow-diagram) for the technical breakdown.
|
|
39
|
+
|
|
40
|
+
## Who handles the card details?
|
|
41
|
+
|
|
42
|
+
The checkout may carry Kelviq's design, but Stripe provides the sensitive payment fields. Stripe.js tokenizes the details inside those fields and returns identifiers Kelviq can use to complete the payment. Kelviq receives the payment result, not the customer's full card number or CVC.
|
|
43
|
+
|
|
44
|
+
Stripe can also request 3D Secure authentication when it is required by the card issuer or recommended for fraud prevention. This adds an identity check without exposing the customer's card details to Kelviq.
|
|
45
|
+
|
|
46
|
+
Banks can still decline or reverse a payment, customers can open disputes, and Stripe or a card network can request a review. Kelviq handles those events as the Merchant of Record.
|
|
47
|
+
|
|
48
|
+
## Where does the money actually sit?
|
|
49
|
+
|
|
50
|
+
During processing, the money appears in Stripe balances. It first appears in Kelviq's Stripe platform balance. After the separate transfer, your share appears in your Stripe connected-account balance. Stripe then sends the payout to your registered bank account.
|
|
51
|
+
|
|
52
|
+
A Kelviq payout balance is not a bank deposit, escrow account, or insured investment. It represents amounts due under the Seller Agreement and can change because of refunds, chargebacks, fees, currency conversion, or a valid reserve.
|
|
53
|
+
|
|
54
|
+
You can track this flow in two places:
|
|
55
|
+
|
|
56
|
+
- The Kelviq **Payouts** dashboard shows processing funds, cleared funds, withdrawals, and payout history.
|
|
57
|
+
- Your Stripe connected-account details show the verified business and bank account used for payouts.
|
|
58
|
+
|
|
59
|
+
Read [Payouts](/payouts/overview) for the dashboard workflow.
|
|
60
|
+
|
|
61
|
+
## What protects my funds if Kelviq closes my account?
|
|
62
|
+
|
|
63
|
+
The Seller Agreement sets out Kelviq's payout obligations and when a payout can be delayed or reserved:
|
|
64
|
+
|
|
65
|
+
- Completed transactions move to your available balance after processing.
|
|
66
|
+
- Final payouts remain due if Kelviq ends the service, subject to open disputes and a permitted reserve.
|
|
67
|
+
- A reserve must have a stated amount or percentage and an expected duration.
|
|
68
|
+
- A post-termination reserve can remain in place for up to 180 days to cover refunds, chargebacks, or other transaction liabilities.
|
|
69
|
+
|
|
70
|
+
This is not a guarantee that nothing can go wrong. A processor failure, bank delay, dispute, compliance action, or insolvency can still affect the timing or recovery of funds. What you do have is a written payment flow, transaction records, and contractual payout terms against which you can check Kelviq's handling of your money. Review [Payout Terms](/legal/master-service-agreement#7-payout-terms) and [Reserves and Holdbacks](/legal/master-service-agreement#8-reserves-and-holdbacks) for the controlling language.
|
|
71
|
+
|
|
72
|
+
## How much notice will I get before a suspension?
|
|
73
|
+
|
|
74
|
+
There is no single advance-notice period for every suspension, including every non-fraud suspension. Kelviq may need to act quickly because of suspected fraud, prohibited activity, failed verification, a legal requirement, a payment-network instruction, or a restriction on the connected Stripe account.
|
|
75
|
+
|
|
76
|
+
The 30-day notice in the Seller Agreement applies when Kelviq terminates an account for convenience. It does not apply to the grounds for immediate termination listed in that agreement. If you believe a policy suspension or termination was made in error, you can appeal it. Kelviq responds to appeals within 10 business days under the [Acceptable Use Policy](/legal/approved-prohibited-policy#83-appeal-process).
|
|
77
|
+
|
|
78
|
+
### Will my customers' subscriptions cancel immediately?
|
|
79
|
+
|
|
80
|
+
Not in every case. A suspension and a subscription cancellation are separate actions. However, Kelviq may need to block checkout or future renewals, depending on why the account was restricted. The Seller Agreement does not promise uninterrupted subscription collection during a suspension. If a notice does not clearly say which functions are affected, contact [support@kelviq.com](mailto:support@kelviq.com) before making changes for your customers.
|
|
81
|
+
|
|
82
|
+
## Where do the Stripe Customer and Subscription records live?
|
|
83
|
+
|
|
84
|
+
Kelviq manages the buyer-facing Stripe Customer, PaymentIntent, invoice, and Subscription records on its Stripe platform account. Your Stripe Express connected account receives transfers and payouts; it does not receive an independent copy of every platform billing object.
|
|
85
|
+
|
|
86
|
+
An ID such as `cus_...` or `sub_...` points to an object inside the Stripe account where it was created. It cannot simply be reassigned to another Stripe account. Under the [Seller Agreement](/legal/master-service-agreement#111-buyer-data), Kelviq controls buyer payment and transaction data in its role as Merchant of Record. You still own your product and content, and Kelviq provides the buyer information needed for fulfillment and customer support.
|
|
87
|
+
|
|
88
|
+
## Can I move to another provider?
|
|
89
|
+
|
|
90
|
+
A billing migration is possible in some cases, but it is not an automatic account transfer. Contact [support@kelviq.com](mailto:support@kelviq.com) before closing your Kelviq account or disconnecting Stripe. Kelviq will review the request with Stripe and the receiving provider, then explain what can be transferred.
|
|
91
|
+
|
|
92
|
+
Stripe supports secure exports of eligible card data to a PCI DSS Level 1 payment processor. Some credentials, including cards saved through Link, cannot be exported. Subscription records and payment history also need to be mapped or recreated in the new billing system; moving card data alone does not move an active subscription.
|
|
93
|
+
|
|
94
|
+
Migration scope and timing depend on the receiving provider, Stripe's requirements, applicable privacy rules, and any unresolved refunds, disputes, or reserves. See [Stripe's payment-data export process](https://docs.stripe.com/get-started/data-migrations/pan-export) for the processor-level requirements.
|
|
95
|
+
|
|
96
|
+
## Questions about your account
|
|
97
|
+
|
|
98
|
+
For an account-specific explanation of a payout, reserve, suspension, or migration, email [support@kelviq.com](mailto:support@kelviq.com). Include your Kelviq business name and the relevant transaction, payout, or subscription IDs, but never send a full card number or CVC.
|
|
@@ -132,11 +132,11 @@ There are two steps to complete before you can start accepting real payments:
|
|
|
132
132
|
|
|
133
133
|
### Step 1: Business Verification
|
|
134
134
|
|
|
135
|
-
|
|
135
|
+
Open **Settings → Business details** in the Kelviq dashboard. You can also continue from the business-verification prompt shown during onboarding.
|
|
136
136
|
|
|
137
|
-
<img src="/images/review-process/business-verification-prompt.png" alt="Business
|
|
137
|
+
<img src="/images/review-process/business-verification-prompt.png" alt="Business verification prompt shown during onboarding" />
|
|
138
138
|
|
|
139
|
-
Fill in your business details and click **Submit for review** when you're done.
|
|
139
|
+
Fill in your business details and click **Submit for review** when you're done. Kelviq places the country from your organization profile first in the country selector to make it easier to find. Review the country before submitting the form.
|
|
140
140
|
|
|
141
141
|
<img src="/images/review-process/business-details-form.png" alt="Business details form" />
|
|
142
142
|
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Agent Toolkit"
|
|
3
|
+
slug: "guides/agent-toolkit"
|
|
4
|
+
section: "guides"
|
|
5
|
+
description: "Install Kelviq into Claude Code with one plugin — or add the Kelviq skills to any of 70+ AI coding agents."
|
|
6
|
+
---
|
|
7
|
+
The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
|
|
8
|
+
|
|
9
|
+
Skills are the missing half of tool access. The MCP server gives your agent 45 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
|
|
10
|
+
|
|
11
|
+
**The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Install — Claude Code
|
|
16
|
+
|
|
17
|
+
Two commands, in any Claude Code session:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
/plugin marketplace add kelviq/agent-toolkit
|
|
21
|
+
/plugin install kelviq@kelviq
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This installs the full bundle: the MCP server is configured for you (no `claude mcp add`, no `--` separator gotchas) and all five skills are available immediately.
|
|
25
|
+
|
|
26
|
+
The server reads your API keys from environment variables. It uses your **sandbox** environment unless `KELVIQ_ENV=production`, so start with sandbox keys. Set them in your shell profile before starting Claude Code:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
export KELVIQ_SERVER_API_KEY="<your-sandbox-server-key>"
|
|
30
|
+
export KELVIQ_CLIENT_API_KEY="<your-sandbox-client-key>" # only needed for promotion_get
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
|
|
34
|
+
|
|
35
|
+
**Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 45 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
|
|
36
|
+
|
|
37
|
+
No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Install — any other agent
|
|
42
|
+
|
|
43
|
+
The five skills are also published through the open skills ecosystem, installable into 70+ agents (Cursor, Codex, GitHub Copilot, OpenCode, Zed, and more):
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx skills add kelviq/agent-toolkit
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Add `--skill <name>` to install a single skill instead of the full set:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npx skills add kelviq/agent-toolkit --skill setup-payments
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
This path installs **skills only** — it doesn't configure an MCP server for you. Each skill starts with a short Setup section showing the `.mcp.json` snippet to connect `@kelviq/mcp-server` on your agent; see the [MCP server guide](/guides/mcp-server) for client-specific instructions.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## The five skills
|
|
60
|
+
|
|
61
|
+
| Skill | What it teaches |
|
|
62
|
+
|---|---|
|
|
63
|
+
| `kelviq` | The hub. Connecting any agent to Kelviq, the ground rules (docs-first, error handling, confirm-before-destructive), the concept model (identifiers vs UUIDs, feature types, plan lifecycle, environments), and routing to the right skill or prompt for the task. |
|
|
64
|
+
| `pricing-plans` | Designing and publishing the catalog: products, features, plans, entitlements, the DRAFT → publish lifecycle, and customer-migration decisions on publish. |
|
|
65
|
+
| `setup-payments` | Selling plans and managing subscribers: checkout sessions, subscriptions, trials, upgrades, cancellation, and authenticated customer portal links. |
|
|
66
|
+
| `usage-based-billing` | Enforcing what was sold: runtime entitlement checks served from the edge, safe usage reporting for metered features, and the license key lifecycle. |
|
|
67
|
+
| `pricing-as-code` | The [Kelviq CLI](/cli/overview) workflow: pull the live catalog into `kelviq.config.ts`, edit in git, preview the diff, apply, and promote sandbox to production. |
|
|
68
|
+
|
|
69
|
+
### `kelviq` — the hub
|
|
70
|
+
|
|
71
|
+
Loads for any Kelviq task that doesn't match a more specific skill. It carries the knowledge every other skill assumes:
|
|
72
|
+
|
|
73
|
+
- **Identifiers vs UUIDs** — when an endpoint wants the URL-safe `identifier` and when it wants the UUID, and how to resolve one from the other.
|
|
74
|
+
- **Feature types** — `BOOLEAN` (flag), `CUSTOMIZABLE` (numeric quantity), `METER` (usage-tracked), and how entitlement shapes differ per type.
|
|
75
|
+
- **Plan lifecycle** — plans are created in DRAFT and invisible until published; updating a published plan creates a new draft.
|
|
76
|
+
- **Environments** — sandbox by default, `KELVIQ_ENV=production` only for live data, and why "not found" errors often mean "right key, wrong environment".
|
|
77
|
+
- **A customer-access diagnosis flow** — comparing what a customer *has* (`entitlements_get`), what they *bought* (`subscription_list`), and what their plan *grants* (`plan_entitlements_list`).
|
|
78
|
+
|
|
79
|
+
### `pricing-plans`
|
|
80
|
+
|
|
81
|
+
The golden path from empty account to published plan: create the product, create the features, create the plan (in DRAFT), attach entitlements, set prices, publish, verify. Includes the two decisions agents most often get wrong: whether to migrate existing customers on publish (`updateFeatures` / `updatePricing` — always a deliberate, confirmed choice), and where prices are managed (the dashboard or the CLI — the MCP server deliberately has no price-write tool).
|
|
82
|
+
|
|
83
|
+
### `setup-payments`
|
|
84
|
+
|
|
85
|
+
Checkout-first selling. The skill teaches that `checkout_create_session` is the default way to charge a customer — direct subscription creation charges off-session and is only enabled for some organizations — plus trial handling (`trialEnd`), safe plan changes (`paymentBehavior`), cancellation types, and the customer portal (always the signed URL from `portal_session_create`; a bare portal URL doesn't authenticate).
|
|
86
|
+
|
|
87
|
+
### `usage-based-billing`
|
|
88
|
+
|
|
89
|
+
Runtime enforcement. Entitlement checks via the edge-served `entitlements_get` (built to be cheap enough to call on the request path), the difference between `SET` and `DELTA` usage reporting — and why a blindly retried `DELTA` double-counts — plus license key activation, validation, and deactivation with `instanceId` handling.
|
|
90
|
+
|
|
91
|
+
### `pricing-as-code`
|
|
92
|
+
|
|
93
|
+
Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `kelviq.config.ts` in a branch → `kelviq push --dry-run` → review → apply → `kelviq promote` from sandbox to production. The skill has a built-in safety rule: an agent may run dry-runs and show you diffs freely, but **applying a real change always requires your explicit approval** — it will never chain a dry-run into an unattended `--yes`.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Skills, prompts, and tools — how they fit
|
|
98
|
+
|
|
99
|
+
The toolkit layers three things, each doing what it's best at:
|
|
100
|
+
|
|
101
|
+
1. **Tools** (from the MCP server) do the work — 45 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
|
|
102
|
+
2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
|
|
103
|
+
3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
|
|
104
|
+
|
|
105
|
+
Deep reference detail (field lists, price shapes, config schemas) intentionally lives in none of these — the skills direct the agent to `docs_search` / `docs_read`, so answers always come from the current documentation.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Sandbox and production
|
|
110
|
+
|
|
111
|
+
The bundled server uses your **sandbox** environment unless you set `KELVIQ_ENV=production` — separate data, separate keys, nothing crosses between them. Build and test in sandbox, and switch to production (with production API keys) only when you want the agent to work with live data. See the [sandbox guide](/guides/sandbox) for details.
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
export KELVIQ_ENV="production"
|
|
115
|
+
export KELVIQ_SERVER_API_KEY="<your-production-server-key>"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Updating
|
|
121
|
+
|
|
122
|
+
- **MCP server**: nothing to do. The toolkit runs `npx -y @kelviq/mcp-server@latest`, which checks for the newest published version each time the server starts.
|
|
123
|
+
- **Skills** (Claude Code): `/plugin marketplace update kelviq` pulls the latest marketplace content.
|
|
124
|
+
- **Skills** (other agents): re-run `npx skills add kelviq/agent-toolkit`.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Troubleshooting
|
|
129
|
+
|
|
130
|
+
**`kelviq:` tools aren't available** — on Claude Code, check `/mcp`; if the server isn't listed, reinstall the plugin. On other agents, the skills-only install doesn't include the server — follow the Setup section in any installed skill or the [MCP server guide](/guides/mcp-server).
|
|
131
|
+
|
|
132
|
+
**`Configuration error` from API tools** — `KELVIQ_SERVER_API_KEY` isn't visible to the process that launched your agent. Set it in your shell profile (not just the current terminal) and restart the agent.
|
|
133
|
+
|
|
134
|
+
**"Not found" on an identifier you can see in the dashboard** — your key and `KELVIQ_ENV` are probably pointing at the other environment. Sandbox and production are fully separate; a key only works against its own environment.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Related
|
|
139
|
+
|
|
140
|
+
- [MCP server guide](/guides/mcp-server) — manual per-client setup, full tool list, architecture
|
|
141
|
+
- [Kelviq CLI](/cli/overview) — the pricing-as-code workflow the `pricing-as-code` skill teaches
|
|
142
|
+
- [Sandbox](/guides/sandbox) — test environment setup
|
|
143
|
+
- [github.com/kelviq/agent-toolkit](https://github.com/kelviq/agent-toolkit) — the toolkit source
|
|
@@ -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,23 +42,22 @@ 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
59
|
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 45 tools`.
|
|
57
60
|
|
|
58
|
-
### Claude Desktop
|
|
59
|
-
|
|
60
61
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
|
|
61
62
|
|
|
62
63
|
```json
|
|
@@ -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:
|
|
82
|
+
|
|
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
|
+
```
|
|
98
|
+
|
|
99
|
+
Project-level config overrides global config when a server of the same name exists in both.
|
|
100
|
+
|
|
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:
|
|
80
128
|
|
|
81
|
-
|
|
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.
|
|
82
148
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
+
```
|
|
88
169
|
|
|
89
|
-
|
|
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.
|
|
@@ -118,21 +199,12 @@ Your AI client should pick the right tool, call it, and show the result inline.
|
|
|
118
199
|
|----------|----------|---------|---------|
|
|
119
200
|
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
|
|
120
201
|
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
|
|
121
|
-
| `KELVIQ_ENV` | No | `
|
|
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. |
|
|
122
203
|
| `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
|
|
123
204
|
| `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
|
|
124
205
|
|
|
125
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.
|
|
126
207
|
|
|
127
|
-
### Point at Staging
|
|
128
|
-
|
|
129
|
-
```env
|
|
130
|
-
KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
|
|
131
|
-
KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
Pair these with a **staging-scoped** Server API Key from your dashboard's staging environment.
|
|
135
|
-
|
|
136
208
|
---
|
|
137
209
|
|
|
138
210
|
## Tool Reference
|
|
@@ -239,8 +311,8 @@ Resources let your AI client pin pages into context. The server advertises three
|
|
|
239
311
|
|
|
240
312
|
| URI pattern | Content |
|
|
241
313
|
|-------------|---------|
|
|
242
|
-
| `kelviq://docs/{section}/{slug}` | Every
|
|
243
|
-
| `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) |
|
|
244
316
|
| `kelviq://README` | Top-level Kelviq overview |
|
|
245
317
|
|
|
246
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.
|
|
@@ -325,16 +397,24 @@ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to
|
|
|
325
397
|
```bash
|
|
326
398
|
claude mcp add kelviq \
|
|
327
399
|
--env KELVIQ_SERVER_API_KEY=... \
|
|
328
|
-
-- npx -y @kelviq/mcp-server
|
|
400
|
+
-- npx -y @kelviq/mcp-server@latest
|
|
329
401
|
```
|
|
330
402
|
|
|
331
403
|
### Tool returns `{"error": {"status": "Configuration error", ...}}`
|
|
332
404
|
|
|
333
405
|
A required env var is missing. The error message names which one — set it in your client config and reconnect.
|
|
334
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
|
+
|
|
335
415
|
### Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
|
|
336
416
|
|
|
337
|
-
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`.
|
|
338
418
|
|
|
339
419
|
### Test Without an AI Client
|
|
340
420
|
|
|
@@ -343,7 +423,7 @@ Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspect
|
|
|
343
423
|
```bash
|
|
344
424
|
KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
|
|
345
425
|
npx -y @modelcontextprotocol/inspector \
|
|
346
|
-
npx -y @kelviq/mcp-server
|
|
426
|
+
npx -y @kelviq/mcp-server@latest
|
|
347
427
|
```
|
|
348
428
|
|
|
349
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:
|