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
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /health | Liveness check | none |
| GET | /.well-known/mcp | Public discovery/manifest (server info + tool list) | none |
| POST | / | JSON-RPC 2.0 endpoint — initialize, tools/list, tools/call | session; tools/call also needs a bearer token |
| GET | / | Standalone SSE stream (server-initiated messages, keep-alive) | session |
| DELETE | / | Terminate a session | session |
MCP session lifecycle
POST /withmethod: "initialize"— no auth required. Returns anMcp-Session-Idresponse header; every subsequent request must send that value back as theMcp-Session-Idrequest header.POST /withmethod: "tools/list"— session required, no bearer token needed. Returns the tool manifest.POST /withmethod: "tools/call"— session andAuthorization: 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
| Tool | Purpose |
|---|---|
query_business_checking | Filter business checking listings (fees, entity types, states, RTP rails, integrations, APY, etc.) |
get_business_checking_listing | Full detail on one listing by listing_slug — fees and features, including per-plan-tier breakdowns |
See src/lib/tools.ts for the full JSON Schema of each tool's arguments, or query GET /.well-known/mcp / tools/list directly.
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.devenabled. Deployed automatically by CI on every push/PR tomain. - production —
bancadia-mcp-production, routed atmcp.bancadia.com/*. Deployed manually vianpm 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.