OpenWallet MCP Server

MCP server providing Vietnamese bank card data tools. Hosted at mcp.openwallet.vn.

Authentication

All requests require X-MCP-Key header (or Authorization: Bearer <key>).

X-MCP-Key: your-api-key

Contact OpenWallet to get an API key.

Inspector

To explore and test tools interactively, use the hosted MCP Inspector:

https://inspector.openwallet.vn

1. Open the URL
2. Click Connect

Transport and server URL are pre-configured. See inspector/ for deployment details.

Read more about MCP Inspector

Tools

banks

List all banks issuing cards in Vietnam.

findBank(query)

Find a bank by name or alias. Supports: "vcb", "a chau", "ngân hàng ngoại thương", etc. Returns first match or null.

intents

List all valid intent slugs for use in cards and rank.

cards(q?, bank_id?, type?, network?, intent?, limit?)

Search cards by filter. Use for browsing cards by bank/type/network/intent. For "best card for spending X", use rank instead.

card(card_id)

Get full details for a single card by ID. Use findCard first if you only have a name.

findCard(query)

Find a card ID from a name or description. E.g. "thẻ đen techcombank", "shopee vpbank". Returns { id, name, bank_id, confidence: "exact" } when unambiguous, or { confidence: "ambiguous", matches, message } when multiple cards match.

rank(spend, limit?, type?)

Primary tool for card recommendations. Ranks all cards by actual spend profile.

{ "spend": { "ecommerce": 5000000, "dining": 2000000 }, "limit": 3, "type": "credit" }

Returns ranked list with estimated monthly cashback.

compare(card_ids)

Compare 2–4 cards side-by-side by ID.

Badge

Embed live MCP status in any site:

Markdown:

[![MCP v0.1.0](https://img.shields.io/endpoint?url=https%3A%2F%2Fmcp.openwallet.vn%2Fbadge&cacheSeconds=60)](https://mcp.openwallet.vn/health)

HTML:

<a href="https://mcp.openwallet.vn/health">
  <img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fmcp.openwallet.vn%2Fbadge&cacheSeconds=60" alt="MCP Status">
</a>

Local Development

# 1. Install
pnpm install

# 2. Set secrets in .dev.vars
cp .dev.vars.example .dev.vars
# Fill in MCP_API_KEY, OPENWALLET_API_KEY
# Set OPENWALLET_API_URL=http://localhost:8787 for local API

# 3. Start API repo (port 8787) in another terminal — `pnpm dev` in api repo

# 4. Run MCP locally
pnpm dev   # → http://localhost:8787

Deployment

wrangler secret put MCP_API_KEY
wrangler secret put OPENWALLET_API_KEY
pnpm deploy

Then add custom domain mcp.openwallet.vn in Cloudflare dashboard.