Connect your agent

Connect Claude, Codex or another AI agent to your Kardy merchant workspace.

Agent connections share the workspace’s MCP allowance. 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.

Connect in three steps

OAuth means signing in to Kardy and approving access—no API key to copy.

1. Copy your connection address

   Open the merchant portal → Settings → Agent connections. Copy the MCP endpoint.

2. Add Kardy to your agent

   Choose your client below and follow its instructions. Your agent will open Kardy in your browser.

3. Review and approve

   Sign in to Kardy, choose your merchant and review the permissions. Select Allow read-only access, then return to your agent.

Choose your agent

Codex

Use the endpoint from Settings:

codex mcp add kardy --url https://merchants.getkardy.com/api/mcp
codex mcp login kardy

Follow the browser sign-in. Codex help.

Claude Code

Use your merchant endpoint:

claude mcp add --transport http kardy https://merchants.getkardy.com/api/mcp

Run /mcp inside Claude Code, select Kardy and authenticate. Claude Code help.

Claude / Desktop

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.

Other clients

In VS Code, choose MCP: Add Server → HTTP, paste your endpoint and authenticate. For another client, select Streamable HTTP with OAuth. VS Code help.

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:

Illustrative preview of the real Kardy consent screen. The client, return address and merchant vary with your connection.

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.

My client needs an API key instead

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.

I cannot connect

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 for tool schemas, security rules and deployment details.