cardos-mcp connects CardOS to Claude, Cursor, Windsurf, VS Code and any MCP client. Point your assistant at it and ask, in plain language, to check a balance, issue a card, pull transactions, file a dispute, or start KYC.

It's a thin, safe client over the public CardOS REST API: no provider internals, no secrets in the repo, money operations are idempotent, card details stay masked, and a cms_sk_test_… key runs in sandbox (no real money).

---

Quick start

1. Get an API key → cardos.dev/partner/developers (a cms_sk_test_… key = sandbox).
2. Run it — published to npm:

CARDOS_API_KEY=cms_sk_test_xxx npx -y cardos-mcp

…or straight from source:

git clone https://github.com/CMSCardOS/cardos-mcp && cd cardos-mcp
npm install && npm run build
CARDOS_API_KEY=cms_sk_test_xxx node dist/index.js

Add to your client

Drop this into your client config (env holds your key — see examples/ for Claude Desktop, Cursor, Windsurf and VS Code):

{
  "mcpServers": {
    "cardos": {
      "command": "npx",
      "args": ["-y", "cardos-mcp"],
      "env": { "CARDOS_API_KEY": "cms_sk_test_xxx" }
    }
  }
}

Client	Config file
Claude Desktop	claude_desktop_config.json (Settings → Developer → Edit Config)
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	.vscode/mcp.json (use the examples/vscode.json shape)

Tools (26)

Catalog & balance

Tool	Description
list_products	Card products: code, currency, limits, KYC requirement
get_merchant_rates	Per-merchant pricing
get_balance	End-user available balance

Cards

Tool	Description
issue_card 💳	Issue a virtual card (idempotent; sandbox with a test key)
get_card	Masked details (last4, expiry, status)
freeze_card / unfreeze_card / close_card	Lifecycle (idempotent)
set_card_pin	Set a 4-digit PIN (not stored by CardOS)
set_card_controls	Spend limits + blocked MCC/countries (auto-freeze on breach)
reveal_card	One-time hosted PAN/CVV link (PCI on CardOS)
create_card_session	Hosted manage + transactions screens for the end user
list_card_transactions	Transactions (amount, FX, commission, merchant, MCC, decline)

Deposits

Tool	Description
create_deposit 💳	Crypto deposit invoice (idempotent)
confirm_deposit_sandbox	[sandbox] confirm a pending deposit
simulate_transaction_sandbox	[sandbox] inject a test transaction

Statements, analytics, disputes, KYC, webhooks

Tool	Description
get_statement	Statement (spent/received/fees + lines)
get_spending_analytics	Spending by category
file_dispute / list_disputes / get_dispute / update_dispute	Disputes
start_kyc / get_kyc_status	Hosted KYC flow
register_webhook / list_webhooks	Signed outbound events

Resources & prompts

• Resources — cardos://docs (auth/idempotency/webhooks orientation) and cardos://openapi (the live OpenAPI 3 spec). Clients can read these for context.
• Prompts — issue_card_for_user (guided end-to-end issuance) and integrate_cardos (integration walkthrough).

Example prompts

• "What card products are available?" → list_products
• "Issue a sandbox card for user 123456, then show its details." → issue_card → get_card
• "Top up user 123456 with $100 and confirm it." → create_deposit → confirm_deposit_sandbox
• "Freeze card <id> and set a $50 daily limit." → freeze_card → set_card_controls

Safety

• Sandbox-first — a cms_sk_test_… key never moves real money.
• No secrets in the repo — the key lives in your client config / env.
• Idempotent money ops — issue_card / create_deposit won't double-apply on retry.
• Masked card data — full PAN/CVV only via a one-time hosted link, never through this server or the model.
• See SECURITY.md.

Configuration

Env var	Default	Description
CARDOS_API_KEY	—	Your CardOS API key (required).
CARDOS_BASE_URL	https://cardos.dev/api/v1	Override the API base.

Develop

npm install
npm run build        # tsc → dist/
npm test             # vitest (network mocked)
npm run typecheck

See CONTRIBUTING.md.

Links

• CardOS — https://cardos.dev
• Docs — https://cardos.dev/docs · Reference — https://cardos.dev/reference · OpenAPI — https://cardos.dev/openapi-v1.yaml
• FAQ — FAQ.md · Changelog — CHANGELOG.md
• Model Context Protocol — https://modelcontextprotocol.io

License

MIT