Bancadia MCP

Bancadia MCP

A Model Context Protocol server that lets MCP clients (Claude, other LLM agents, etc.) query Bancadia's registry of business deposit account products (US only) — with structured filters.

Runs as a Cloudflare Worker on Hono, exposing MCP over JSON-RPC 2.0 (Streamable HTTP transport), backed by Supabase (Postgres) with an Upstash Redis caching/rate-limiting layer.

Endpoints

MCP session lifecycle

1. POST / with method: "initialize" — no auth required. Returns an Mcp-Session-Id response header; every subsequent request must send that value back as the Mcp-Session-Id request header.
2. POST / with method: "tools/list" — session required, no bearer token needed. Returns the tool manifest.
3. POST / with method: "tools/call" — session and Authorization: Bearer <token> required. Per-token sliding-window rate limiting applies (X-RateLimit-* response headers on both success and 429).

Responses are plain JSON by default, or Server-Sent Events if the request's Accept header includes text/event-stream.

For production use, obtain a bearer token from the Bancadia developer portal — see bancadia.com/docs for full API documentation.

Available tools

See src/lib/tools.ts for the full JSON Schema of each tool's arguments, or query GET /.well-known/mcp / tools/list directly.

application_url attribution tags

Every application_url returned by tools/call is an absolute https://bancadia.com/go/... link with attribution params appended: src=mcp and qr=<request_id>, where request_id is a UUID generated once per tools/call and also written to every query_match_events row for that call (so a /go click can be joined back to the tool call that surfaced it). Params already present on the stored URL are never overwritten. qr is added for every tool; a tool that records no query_match_events rows (or returns no listings) has nothing for it to join to. Host-prefixing and tagging both happen in one layer, applyApplicationUrlHost in src/lib/urls.ts, applied in src/index.ts.

Clients and agents should pass application_url through unmodified, including its query string. Stripping the params loses attribution for that click.

Getting started

npm install
cp .dev.vars.example .dev.vars   # fill in Supabase + Upstash credentials
npm run dev                      # wrangler dev — local server

wrangler.toml [vars] provides non-secret defaults (test Supabase/Upstash URLs, session TTL, allowed origins) shared by both npm run dev and the test suite; real secrets go in .dev.vars (git-ignored).

Commands

npm run dev               # wrangler dev — local server
npm test                  # vitest run (runs inside workerd via @cloudflare/vitest-pool-workers)
npm run lint              # tsc --noEmit
npm run deploy:staging    # wrangler deploy --env staging
npm run deploy:production # wrangler deploy --env production

Run a single test file:

npx vitest run src/__tests__/query-business-checking.test.ts

Environments

• staging — bancadia-mcp-staging, workers.dev enabled. Deployed automatically by CI on every push/PR to main.
• production — bancadia-mcp-production, routed at mcp.bancadia.com/*. Deployed manually via npm run deploy:production.

Secrets for each environment are set with wrangler secret put <KEY> --env <environment> and are never committed.

Architecture

See CLAUDE.md for a detailed guide to the codebase: request flow, auth/session/rate-limit design, and the Supabase hybrid schema (base tables + per-product-type details tables) that the query handlers are built around.