Bancadia

Quickstart

What is Bancadia?

Bancadia is the trust infrastructure for the agentic economy. 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

Go to bancadia.com/developer/signup and register with your email. No credit card required.

Step 2 — Generate an API token

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 only required to call tools (tools/call); browsing the tool manifest with tools/list needs no auth at all.

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.

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 and pass your token as a bearer header. For Claude Code:

claude mcp add --transport http bancadia https://mcp.bancadia.com/ \
  --header "Authorization: Bearer bcd_YOUR_TOKEN_HERE"

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/",
      "headers": {
        "Authorization": "Bearer bcd_YOUR_TOKEN_HERE"
      }
    }
  }
}

Once connected, the client will discover query_business_checking and get_business_checking_listing through tools/list automatically and can call either 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.
SESSION_ID=$(curl -sD - https://mcp.bancadia.com/ \
  -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 both the session header and a bearer token
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": "query_business_checking",
      "arguments": {
        "monthly_fee_max": 0,
        "available_states": ["CA"],
        "insurance_type": "fdic"
      }
    }
  }'

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/',
    headers: { Authorization: 'Bearer bcd_YOUR_TOKEN_HERE' },
  },
})

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 array of matching listings:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "[{\"institution_name\":\"Example Bank\",\"product_name\":\"Business Checking Pro\",\"monthly_fee\":0, ...}]" }
    ]
  }
}

query_business_checking and get_business_checking_listing are the only tools Bancadia currently routes — use the first to search across listings by filter criteria, then the second (passing the listing_slug from a result) to get full detail, including fees and features, on one specific listing. See the MCP Reference for the full argument list, the exact response shape, and every error code for both tools. To discover the endpoint and tool list programmatically without a JSON-RPC round-trip, fetch bancadia.com/.well-known/mcp.