CardOS MCP Server

Issue and manage virtual cards from any AI assistant — over the Model Context Protocol.

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

Related MCP server: payclaw-mcp

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" }
    }
  }
}

Tools (26)

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

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