> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkardy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect your agent
> Connect Claude, Codex or another AI agent to your Kardy merchant workspace.
export const MerchantFlow = ({type}) => {
const merchantFlows = {
"mcp-read": {
title: "From your question to a read-only answer",
lanes: ["Business Owner", "Your agent", "Kardy"],
scenarios: [{
label: "Read merchant data",
note: "Available on dev; production rollout is separate. Customer records and changes to your business are outside these tools.",
steps: [[0, "Ask about your rewards", "Ask your connected agent which active rewards your business offers and where they can be claimed."], [1, "Request an approved tool", "The agent requests programme, rewards or outlet data using its connection credentials."], [2, "Check access and limits", "Kardy checks the connection, approved permissions, subscription and workspace allowance before returning data."], [2, "Return permitted data", "Only the connected workspace's permitted read-only data is returned. Each results page counts as a tool call."], [1, "Summarise the result", "Your agent uses the returned data to answer. It cannot change rewards, issue stamps or manage your team."]]
}]
},
"mcp-connect": {
title: "From adding Kardy to approving your agent",
lanes: ["Business Owner", "Your agent", "Kardy"],
scenarios: [{
label: "Approve with OAuth",
note: "Only the Owner can approve access. Cancel grants no access; revoking a connection stops new requests but cannot recall data already shared.",
steps: [[0, "Copy your MCP endpoint", "Open Settings → Agent connections in the merchant portal and copy the MCP endpoint."], [1, "Open Kardy sign-in", "Add the endpoint in a compatible OAuth client. The agent opens Kardy in your browser."], [0, "Review and approve access", "Sign in, check the client name and return address, choose your merchant and approve only the read permissions you want to share."], [2, "Return an authorisation code", "After approval, Kardy redirects to the registered client with a short-lived authorisation code."], [1, "Exchange the code securely", "The client exchanges the code using PKCE and receives credentials for the approved connection. No manual API key needs to be copied."], [0, "Try a read-only question", "Return to your agent and ask it to list active rewards. Manage or revoke the connection in Agent connections."]]
}]
},
billing: {
title: "What changes for your subscription and customers",
lanes: ["Business Owner", "Subscription", "Customers"],
scenarios: [{
label: "First payment",
note: "Returning from checkout alone does not activate your business. Finish payment before using paid tools.",
steps: [[0, "Choose your business and plan", "Review the monthly price and any eligible first-month offer. Each business has its own subscription."], [0, "Complete payment", "Finish checkout in Kardy Payments. If payment is unfinished, your paid access has not started."], [1, "Paid access starts", "Once payment is confirmed, your business can use its paid merchant tools and included outlet capacity."], [2, "Join, collect stamps and claim", "Customers can join your active programme. Your team records qualifying visits and confirms eligible reward claims."]]
}, {
label: "Failed renewal",
note: "Saving a new card alone does not settle an outstanding payment. Managers and Staff should ask the Owner to resolve billing.",
steps: [[1, "Renewal payment fails", "Unresolved payment can pause this business's paid merchant access, including access for employees."], [2, "Programme paused", "While service is paused, stamps and reward claims are unavailable. Existing memberships and saved progress remain."], [0, "Resolve the outstanding payment", "Open billing, update the payment method if needed and complete the outstanding payment. Do not buy a second subscription."], [1, "Paid access resumes", "Access resumes after successful payment is confirmed. Choose Check payment status; contact support if access is still paused after payment."], [2, "Continue with saved progress", "Customers can use the active programme again without losing their existing memberships or recorded progress."]]
}, {
label: "Cancel renewal",
note: "Canceling renewal does not automatically refund a payment or delete membership history.",
steps: [[0, "Cancel and check the end date", "Cancel renewal in billing and keep the displayed access end date. Select the correct business first."], [1, "Active until the paid period ends", "Your subscription will not renew, but paid merchant access continues through the period already paid for."], [2, "Keep using the programme", "Customers can continue using the programme normally while the paid period remains active."], [1, "Paid access ends", "If cancellation is not reversed, paid merchant tools become unavailable when the subscription ends."], [2, "Store inactive; progress kept", "The card shows Store inactive. New joins, stamps and claims stop, but existing memberships and saved progress remain."]]
}, {
label: "Undo cancellation",
note: "Undo a scheduled cancellation before the subscription ends. If it has already ended, use Restart Growth monthly instead; the introductory offer does not repeat.",
steps: [[0, "Open billing before the end date", "As the Owner, select the business with a scheduled cancellation and review its remaining paid period."], [0, "Reverse the scheduled cancellation", "Use the subscription management options in Kardy Payments to keep the subscription renewing."], [1, "Renewal continues", "Confirm that cancellation is no longer scheduled and review the next billing date and amount. Future renewals still require successful payment."], [2, "No interruption to the programme", "Reversing cancellation before access ends keeps the programme available. Customers retain their memberships and progress."]]
}]
},
outlets: {
title: "More outlets, one business subscription",
lanes: ["Business Owner", "Kardy Payments", "Kardy"],
scenarios: [{
label: "Add capacity",
note: "Where outlet-quantity billing is enabled. Creating a location does not buy paid capacity.",
steps: [[0, "Select the business", "Outlets belong to one business and use that business's subscription."], [0, "Increase paid outlet quantity", "In Settings → Billing, review the new monthly total and any prorated charge."], [1, "Confirm the extra payment", "Extra capacity waits for payment confirmation; a failed payment does not unlock it."], [2, "Update outlet allowance", "Kardy applies the payment-confirmed quantity to this business."], [0, "Add or activate the outlet", "Save the store details in Locations within your paid allowance. Additional outlets do not receive another introductory offer."]]
}, {
label: "Reduce capacity",
note: "Pausing or deleting a location alone does not reduce your bill.",
steps: [[0, "Pause unwanted locations", "Keep the active outlet count within the lower quantity you intend to buy."], [0, "Schedule a lower quantity", "Use Settings → Billing. The smaller quantity takes effect at the next renewal."], [1, "Renew at the new quantity", "The current period is not automatically refunded."], [2, "Apply confirmed capacity", "Kardy updates the allowance after the billing change is confirmed."]]
}]
},
counter: {
title: "A scan checks. Confirmation records.",
lanes: ["Customer", "Employee", "Kardy"],
scenarios: [{
label: "Earn a stamp",
note: "Slide approval is a development flow; production rollout is separate. Never add a duplicate because a wallet refresh is delayed.",
steps: [[0, "Show membership QR", "Use the membership QR from the customer's Kardy wallet."], [1, "Scan at the right outlet", "Choose the active outlet, then check the returned membership and qualifying purchase."], [2, "Check membership and access", "Scanning identifies the membership. It does not award a stamp."], [1, "Slide to add stamp", "Complete the approval control. An early release does not submit the operation."], [2, "Save the stamp once", "Wait for the confirmed result. Recorded activity is the source of truth."], [0, "Refresh wallet if needed", "The displayed balance can lag behind the recorded stamp. Refresh while online rather than requesting a second stamp."]]
}, {
label: "Redeem a reward",
note: "Timed reward QRs and slide approval are implemented in development; check availability before using this flow in production.",
steps: [[0, "Prepare reward QR", "Open the earned reward and prepare its temporary QR. This does not spend stamps."], [1, "Scan and review", "Choose the active outlet and check the reward details. A membership QR cannot authorise a reward claim."], [2, "Check eligibility", "Kardy checks the code, reward, membership, outlet and programme access. A rejected check must be resolved before continuing."], [1, "Slide to redeem reward", "Confirm the claim once. Do not hand over the reward until success is shown."], [2, "Record the redemption", "The successful claim is recorded once. Stamp rewards deduct their cost; excess stamps carry forward."], [1, "Hand over the reward", "If the result is uncertain, check the original transaction before trying again."]]
}]
},
notifications: {
title: "From a new member to your device",
lanes: ["Owner or Manager", "Kardy", "Device"],
scenarios: [{
label: "Receive an alert",
note: "Push is enabled. Delivery starts at 50 ready notifications or a fixed 15-minute recovery check, then continues while ready work remains. Device settings and connectivity can delay delivery.",
steps: [[0, "Choose alerts for this business", "Open Settings → This device. Preferences are separate for every business and device."], [2, "Allow notifications", "Permission follows Enable notifications. On iPhone or iPad, open the installed Home Screen app first."], [1, "A new member joins", "Kardy records the membership and queues device alerts within the business’s monthly allowance. At the cap, the membership still succeeds but no new alert is queued."], [1, "Recheck access and preferences", "Removed access, disabled preferences or an inactive subscription stops new deliveries."], [2, "Display the notification", "The alert contains no customer names or contact details. Focus settings may suppress its display."], [0, "Open the correct business", "Tapping the alert checks access before selecting the business. The Members page shows the actual record."]]
}]
}
};
const flow = merchantFlows[type];
const [scenarioIndex, setScenarioIndex] = useState(0);
if (!flow) return null;
const scenario = flow.scenarios[scenarioIndex] || flow.scenarios[0];
return {flow.title}.
{flow.scenarios.length > 1 &&
;
};
Agent connections share the workspace's [MCP
allowance](/features/usage-limits). Check **Settings → Usage & limits** for
usage and the reset date.
Ask your agent **“What rewards do we offer?”** or **“Where can they be claimed?”**
Kardy shares your programme, rewards and outlets. Your agent can read them, but cannot change anything.
Merchant-only · Available on dev. Production rollout is separate. You must be
the Owner of a merchant with an active subscription.
## Follow the connection flow
**OAuth means signing in to Kardy and approving access—no API key to copy.**
## Choose your agent
Use the endpoint from Settings:
```sh theme={null}
codex mcp add kardy --url https://merchants.getkardy.com/api/mcp
codex mcp login kardy
```
Follow the browser sign-in. [Codex
help](https://developers.openai.com/codex/mcp).
Use your merchant endpoint:
```sh theme={null}
claude mcp add --transport http kardy https://merchants.getkardy.com/api/mcp
```
Run `/mcp` inside
Claude Code, select Kardy and authenticate. [Claude Code
help](https://code.claude.com/docs/en/mcp).
Open **Customize → Connectors → Add custom connector**. Paste the merchant
endpoint, then connect and sign in to Kardy. Availability depends on your
plan and organisation settings. [Claude
help](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
In VS Code, choose **MCP: Add Server → HTTP**, paste your endpoint and
authenticate. For another client, select **Streamable HTTP** with **OAuth**.
[VS Code
help](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
The localhost examples are for agents running on your computer. Cloud
connectors, including Claude’s remote connector, need a reachable HTTPS
merchant address. Do not publish your local dev server to work around this.
## What the approval page looks like
If you are signed out, Kardy first asks for your merchant email and password.
After sign-in, you’ll see a permission screen like this:
Check the client’s **name and return address**. Only approve a connection you started.
Choose one merchant, and untick anything you do not want to share. **Cancel** grants no access.
Your agent can read only the permissions you approve. Customer records, QR codes,
stamp balances, billing and team settings are not shared.
## Try it, then manage access
Ask **“List our active rewards and their stamp goals.”** If a tool is missing,
reconnect and approve its permission.
Your connection lasts up to **30 days**. To disconnect sooner, open
**Settings → Agent connections → Revoke**. New requests stop immediately;
information already shared with your agent cannot be recalled.
In Agent connections, choose **Create a manual API key**. Name it, choose
read permissions and an expiry, then copy it once into your client’s secret
settings. Use a Bearer Authorization header. Never paste the key into a chat
or URL.
Check that you are the Owner, the merchant subscription is active, and your
agent can reach the endpoint. If access has expired or been revoked,
reconnect. Managers and Staff cannot approve connections.
Building an integration? See the [MCP technical reference](/mcp/reference)
for tool schemas, security rules and deployment details.
Check the client’s **name and return address**. Only approve a connection you started.
Choose one merchant, and untick anything you do not want to share. **Cancel** grants no access.
Your agent can read only the permissions you approve. Customer records, QR codes,
stamp balances, billing and team settings are not shared.
## Try it, then manage access
Ask **“List our active rewards and their stamp goals.”** If a tool is missing,
reconnect and approve its permission.
Your connection lasts up to **30 days**. To disconnect sooner, open
**Settings → Agent connections → Revoke**. New requests stop immediately;
information already shared with your agent cannot be recalled.