Bancadia

Quickstart

What is Bancadia?

Bancadia is the data layer AI agents use to recommend financial products. We maintain a real-time, verified registry of business checking account products from real financial institutions — fees, rates, entity eligibility, integrations, and more — that AI agents can query directly via the Model Context Protocol (MCP).

Instead of scraping bank websites or relying on stale data, your agent sends one structured request and gets back accurate, current product data in a single round-trip.

Step 1 — Create a developer account (optional)

No token needed to query. Add a developer token to get credit for the clicks your agent sends (revenue sharing is coming). If you only want to read listings, skip to Step 3, or use the REST API with a plain GET. To get credit, go to bancadia.com/developer/signup and register with your email. No credit card required.

Step 2 — Generate an API token (optional)

Once registered, navigate to your developer dashboard and create a new API token. Copy the token immediately — it is only shown once. A token is optional: tools/call works without one, and browsing the tool manifest with tools/list needs no auth at all. A token that is sent but invalid is rejected with 401.

Step 3 — Connect

The MCP server lives at a single endpoint: https://mcp.bancadia.com/. Every interaction — discovery and querying — is a JSON-RPC 2.0 POST to that one URL. There are three ways to talk to it, pick whichever fits your setup.

Connect with ?profile=v2. The examples below connect to https://mcp.bancadia.com/?profile=v2, which gives your session the recommended v2 tools: list_business_checking, search_facts, fees_by_type and get_listing. If your client cannot change the URL, send the header X-Bancadia-Profile: v2 with initialize instead. The profile is fixed when the session is created. For now, a session created with neither gets the older query_business_checking and get_business_checking_listing tools.

One thing to know regardless of which option you pick: calling initialize is mandatory before anything else. It returns a Mcp-Session-Id header that every subsequent call must echo back — skip it and tools/list / tools/call fail with 400. See the MCP Reference for the full session lifecycle.

Option A — an MCP-aware client (Claude Code, Claude Desktop, etc.)

If you're using an agent runtime that speaks MCP natively over HTTP, register the endpoint, optionally with your token as a bearer header (omit the header to query anonymously). For Claude Code:

claude mcp add --transport http bancadia "https://mcp.bancadia.com/?profile=v2" \
  --header "Authorization: Bearer bcd_YOUR_TOKEN_HERE"  # optional: credits your clicks

Or, for clients configured via a JSON file (the common mcpServers shape used by Claude Desktop and similar tools):

{
  "mcpServers": {
    "bancadia": {
      "url": "https://mcp.bancadia.com/?profile=v2",
      "headers": {
        "Authorization": "Bearer bcd_YOUR_TOKEN_HERE"
      }
    }
  }
}

Once connected, the client will discover the four v2 tools through tools/list automatically and can call any of them like any other tool. MCP client libraries handle the initializecall and session negotiation internally — you don't need to do anything differently for this transport.

Option B — raw JSON-RPC over HTTP

No MCP client required — this is a plain HTTP endpoint, so any language or agent framework that can send a JSON POSTcan use it directly. It's a two-step flow: call initialize to get a session ID, then pass that session ID on every call after it.

# 1. Initialize — no auth required, returns a session ID via the Mcp-Session-Id
#    response header. This step is mandatory; every other call depends on it.
#    ?profile=v2 selects the v2 tools for this session.
SESSION_ID=$(curl -sD - "https://mcp.bancadia.com/?profile=v2" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "example-client", "version": "1.0.0" }
    }
  }' -o /dev/null | grep -i 'Mcp-Session-Id' | tr -d '\r' | cut -d' ' -f2)

# 2. Call a tool — needs the session header; the bearer token is optional (credits your clicks)
curl https://mcp.bancadia.com/ \
  -H "Authorization: Bearer bcd_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_business_checking",
      "arguments": {
        "monthly_fee_max": 0,
        "available_states": ["CA"],
        "insurance_type": "fdic",
        "limit": 5
      }
    }
  }'

Sessions idle-expire after about 30 minutes; a call with a missing or expired session ID gets back 400 or 404 respectively — just call initialize again to get a new one. See the MCP Reference for the complete error reference.

Option C — Vercel AI SDK (createMCPClient)

If your agent is built on the Vercel AI SDK (ai v6+), @ai-sdk/mcp gives you a client that speaks this server's transport directly — it handles initialize and the Mcp-Session-Id lifecycle for you, and client.tools() converts the live tools/list manifest straight into AI SDK tools, so you never hand-copy a schema that can drift out of sync with the server.

import { createMCPClient } from '@ai-sdk/mcp'
import { streamText, stepCountIs } from 'ai'

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.bancadia.com/?profile=v2',
    headers: { Authorization: 'Bearer bcd_YOUR_TOKEN_HERE' }, // optional: credits your clicks
  },
})

const tools = await mcpClient.tools()

const result = streamText({
  model: yourModel,
  messages,
  tools,
  stopWhen: stepCountIs(3),
  onFinish: async () => {
    await mcpClient.close()
  },
})

Create one client per request (or per short-lived process) rather than holding one open indefinitely — close it once your turn is done, as above, so an idle session doesn't outlive the request. Watch your lockfile: @ai-sdk/mcp, ai, and any other @ai-sdk/* provider packages you use all depend on @ai-sdk/provider / @ai-sdk/provider-utils, and if npm resolves two different copies you can get either a type error (@ai-sdk/mcp's tool output not assignable to streamText's expected tools type) or a build-time does-not-exist export error from a bundler like Turbopack. Run npm ls @ai-sdk/provider-utilsand confirm everything dedupes to one version; if it doesn't, add an overrides entry in package.json pinning @ai-sdk/provider and @ai-sdk/provider-utils to whichever single version satisfies every package that depends on them (generally the newest one requested, not the oldest — an older pin can be missing exports a newer dependency needs at runtime).

Step 4 — Read the response

The result comes back as a JSON-RPC response whose result.content[0].text field is a JSON-encoded string, not native JSON — parse it to get the matching listings. The v2 list result is paged (7 rows by default, up to 20 with limit) and includes total_matches and next_offset; pass next_offset as offset to get the next page. The exact shape is in the MCP Reference. Illustrative payload:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"total_matches\":13,\"returned\":5,\"limit\":5,\"next_offset\":5,\"rows\":[{\"listing_slug\":\"example-business-checking-pro\",\"institution_name\":\"Example Bank\",\"product_name\":\"Business Checking Pro\",\"monthly_fee\":0,\"application_url\":\"https://bancadia.com/go/...\"}, ...],\"notes\":\"Absent field = not offered or not published; ...\"}" }
    ]
  }
}

Use list_business_checking to search across listings by filter criteria, get_listing (passing listing_slug values from a result) for detail such as fees and features, fees_by_type to compare specific fees across banks, and search_facts to search fee and feature details by keyword. A field missing from a result means the account does not offer it or the bank has not published it; give each application_url to the user exactly as returned. Prefer plain HTTP? The same data is in the REST API. See the MCP Reference for the full argument list, the exact response shape, and every error code. The legacy tools (query_business_checking, get_business_checking_listing) are still the default for connections that do not ask for v2 and remain documented there. To discover the endpoint and tool list programmatically without a JSON-RPC round-trip, fetch bancadia.com/.well-known/mcp.