Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CardOS MCP Server What card products are available?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Get an API key → cardos.dev/partner/developers (a cms_sk_test_… key = sandbox).
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.jsRelated MCP server: ASG Card
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 |
|
Cursor |
|
Windsurf |
|
VS Code |
|
Tool | Description |
| Card products: code, currency, limits, KYC requirement |
| Per-merchant pricing |
| End-user available balance |
Tool | Description |
| Issue a virtual card (idempotent; sandbox with a test key) |
| Masked details (last4, expiry, status) |
| Lifecycle (idempotent) |
| Set a 4-digit PIN (not stored by CardOS) |
| Spend limits + blocked MCC/countries (auto-freeze on breach) |
| One-time hosted PAN/CVV link (PCI on CardOS) |
| Hosted manage + transactions screens for the end user |
| Transactions (amount, FX, commission, merchant, MCC, decline) |
Tool | Description |
| Crypto deposit invoice (idempotent) |
| [sandbox] confirm a pending deposit |
| [sandbox] inject a test transaction |
Tool | Description |
| Statement (spent/received/fees + lines) |
| Spending by category |
| Disputes |
| Hosted KYC flow |
| Signed outbound events |
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).
"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
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.
Env var | Default | Description |
| — | Your CardOS API key (required). |
|
| Override the API base. |
npm install
npm run build # tsc → dist/
npm test # vitest (network mocked)
npm run typecheckSee CONTRIBUTING.md.
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
Close a card permanently (irreversible). Idempotent.
Inputs: card_id (required).
[SANDBOX] Simulate confirmation of a pending deposit (test key only). In live, an on-chain watcher credits it.
Inputs: deposit_id (required).
Mint hosted card screens (manage + transactions) on real data, to open in a webview for the end user — bypassing you. Returns manage_url / transactions_url.
Inputs: card_id (required).
Create a crypto deposit invoice to top up an end-user balance. Money operation — sandbox with a test key. Idempotent.
Inputs: amount (required), external_user_ref (required), method.
Open a dispute on a transaction.
Inputs: reason (required), transaction_id (required), note.
Freeze a card (reversible). Idempotent.
Inputs: card_id (required).
Get an end user's available balance.
Inputs: external_user_ref (required).
Masked card details (last4, expiry, status). Raw PAN/CVV are never returned here — use reveal_card.
Inputs: card_id (required).
Get one dispute by id.
Inputs: dispute_id (required).
Status of a KYC session by uuid.
Inputs: uuid (required).
Per-merchant pricing for products (e.g. for github, google).
Inputs: merchant (required).
Spending breakdown by category (from MCC) for an end user.
Inputs: external_user_ref (required), days.
An end user's statement (summary: spent/received/fees/holds + line items + balance).
Inputs: external_user_ref (required), days.
💳 Issue a virtual card to an end user. Money operation — a test key runs in sandbox (no real money). Idempotent: retries do not double-issue.
Inputs: external_user_ref (required), product.
List transactions for a card (amount, currency, commission, FX original amount/currency, merchant, MCC, decline reason, status).
Inputs: card_id (required), limit.
List disputes, optionally filtered by user or status.
Inputs: limit, status, external_user_ref.
List available card products: productCode, currency, issue/topup limits, and whether KYC is required.
Inputs: no named parameters.
List registered webhook endpoints (no secrets).
Inputs: no named parameters.
Register an HTTPS endpoint for outbound events (transaction, balance, issued, card_status, kyc). Returns the signing secret once.
Inputs: url (required), events.
Mint a one-time hosted link that shows full card details (PAN/CVV) to the end user, bypassing you (PCI on CardOS). Short-lived, single-use.
Inputs: card_id (required).
Set soft spend controls (per-transaction / daily / monthly limits, blocked MCC/countries). On breach the card is auto-frozen + an alert is sent (no hard auth-time block).
Inputs: card_id (required), blocked_mcc, blocked_country, daily_max_minor, +2 more.
Set a 4-digit PIN. The PIN is not stored by CardOS.
Inputs: pin (required), card_id (required).
[SANDBOX] Inject a test card transaction (test key only) to exercise webhooks, analytics, controls and cashback.
Inputs: amount (required), card_id (required), mcc, type, +2 more.
Start KYC for an end user. Returns a hosted url_for_user and a uuid to poll.
Inputs: external_user_ref (required), sort.
Unfreeze a frozen card. Idempotent.
Inputs: card_id (required).
Update a dispute (status / note / provider reference).
Inputs: dispute_id (required), note, status, provider_ref.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 26 tools
Each tool targets a distinct operation on a specific resource (e.g., card, deposit, dispute, KYC, webhook). No two tools have overlapping purposes; descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern using snake_case. The naming convention is uniform across the entire set, making it predictable and easy to navigate.
With 26 tools, the count is slightly above the typical 3-15 range, but the breadth of card operations (issuing, management, disputes, KYC, webhooks) justifies the number. It is still reasonable and not overly bloated.
The tool surface covers the full lifecycle of card management, deposits, disputes, KYC, webhooks, and analytics. Essential CRUD operations are present, and sandbox tools support testing. Missing operations are minor and non-critical.
Prepaid virtual cards for AI agents: one-time cards, spend caps, human approvals.
Financial intelligence for AI: manage balances, transactions, payments, and more
Give your AI agent a spending limit: approval controls and single-use virtual cards.
Connect AI agents to financial institution origination, analytics, and compliance workflows.
