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 required; Authorization: Bearer is optional (no header = anonymous, rate limited per IP; an invalid token is a 401). Sliding-window rate limiting applies (per token, or per IP via ANON_RATE_LIMIT_REQUESTS / ANON_RATE_LIMIT_WINDOW_SECONDS, default 60 / 60s) (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, optionally obtain a bearer token (credits usage to you) 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= , where request_id is a UUID generated once per tools/call and also written as that call's query_events.request_id and on each of its query_match_events rows (so a /go click can be joined back to the tool call, and listing, that surfaced it). Params already present on the stored URL are never overwritten. Every call to a known tool gets a query_events row — including zero-result calls, calls rejected for invalid arguments (status = 'invalid_args') and failed calls (status = 'error') — while query_match_events holds one row per returned listing. 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 --env 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.