MCP Server Guide

Connect AI agents like Claude Code, Claude Desktop, and Cursor to your BankSync data through the remote MCP server at mcp.banksync.io.

6 min read

On this page

What is MCP?
What agents can do
Plan requirements and rate limits
Step 1: Create an API key
Step 2: Connect your client
Claude Code
Claude Desktop
Cursor
Other clients
Alternative: the npx bridge for stdio-only clients
Security and scope guidance
Confirm it worked
Troubleshooting
Related guides

The BankSync MCP server gives AI agents secure, scoped access to your financial data. Ask Claude about your spending, have an agent check balances across every connected bank, or let it manage feeds and trigger syncs, all in natural language.

The API key setup that powers MCP clients.

BankSync's MCP server is remote and hosted: it lives at https://mcp.banksync.io and speaks the MCP Streamable HTTP transport. There is nothing to install and no local server to run. You authenticate with a workspace API key sent in the X-API-Key header.

Hosted & remote

Connect any MCP client to https://mcp.banksync.io. No install, no localhost.

Scoped API keys

Each key carries only the permission scopes you grant it.

Natural language

Query transactions, balances, holdings, and loans conversationally.

What is MCP?#

Model Context Protocol (MCP) is an open standard that lets AI models connect to external data sources and tools. Once your agent is connected to BankSync, it can call BankSync tools directly: no copy-pasting CSVs, no screenshots of your banking app.

Example queries

"How much did I spend on restaurants last month?" • "What's my current checking account balance?" • "Show me my largest expenses this week" • "Trigger a sync on my Transactions feed" • "Which of my feeds failed their last run?"

What agents can do#

The server exposes tools across your whole workspace. The major groups:

Read financial data

Accounts, transactions, balances, holdings, trades, and loans (get_transactions, get_balance, get_holdings, list_accounts, and more)

Manage feeds & syncs

List, create, update, and validate feeds; trigger syncs; watch and cancel jobs

Banks & institutions

List connected banks, search supported institutions, and create bank connection links

Enrichments & portals

Create and preview enrichment rules, and manage client portals

For the full tool list with parameters and example calls, see the MCP tools reference.

MCP is not read-only by default

The server includes write tools (create and delete feeds, trigger syncs, connect and delete banks, manage enrichments and portals). What an agent can actually do is decided entirely by the scopes on the API key you give it, so a key with only read scopes makes the connection effectively read-only.

Plan requirements and rate limits#

MCP access requires the Standard plan or above. Each plan sets a per-minute request rate for MCP tool calls:

Plan	MCP access	Rate limit
Free	No	n/a
Starter	No	n/a
Standard	Yes	15 requests/min
Professional	Yes	30 requests/min
Business	Yes	300 requests/min

If your key returns a plan-gating error, upgrade from Settings > Billing. See Changing your plan.

Australian (CDR) banks are not available via MCP

Data from Australian banks connected through the Consumer Data Right (CDR) is not currently exposed through the MCP server, while our accreditation partner reviews AI access to CDR data. MCP requests for a CDR-connected bank return a restriction notice instead of data, and feeds from CDR banks can't be created through MCP. US, Canadian, UK, and EU connections are unaffected. To analyse CDR data, route it to a destination you control (a spreadsheet, Notion, Airtable, or your own database) and work with it there.

Step 1: Create an API key#

The MCP server authenticates with the same workspace API keys as the REST API. Keys start with bsk_ and are shown in full exactly once, at creation.

Get your key

Open Settings > Developers
In your workspace, open Settings, then the Developers section under the Workspace group. The API Keys panel lists existing keys.
Create a key
Click Create Key, name it (for example "Claude Desktop"), and pick an expiration.
Choose scopes carefully
Select only the scopes your agent needs. For a chat assistant that only answers questions about your data, grant read scopes only (banks:read, feeds:read, jobs:read). Add write scopes only if the agent should create feeds, trigger syncs, or change things.
Copy the secret
Copy the full bsk_ key when it is revealed. It cannot be retrieved later.

The full creation flow, the scopes model, and revocation are covered in API keys.

The Create API Key dialog with a key name filled in and per-resource read and write permission scopes selected. — Create a key with only the scopes your agent needs; read-only scopes make the connection read-only.

Step 2: Connect your client#

Most modern MCP clients support remote servers over Streamable HTTP. You give them three things: the URL https://mcp.banksync.io, the header name X-API-Key, and your key.

Claude Code#

The fastest path is one CLI command:

Shell

claude mcp add --transport http banksync https://mcp.banksync.io \  --header "X-API-Key: bsk_your_api_key_here"

Or commit a project-level .mcp.json to your repo root (Claude Code expands environment variables, so the secret stays out of source control):

JSON

{  "mcpServers": {    "banksync": {      "type": "http",      "url": "https://mcp.banksync.io",      "headers": {        "X-API-Key": "${BANKSYNC_API_KEY}"      }    }  }}

Verify the connection

Run /mcp inside Claude Code to confirm the banksync server is connected and to browse its tools, then try "List my workspaces" as a first prompt.

Claude Desktop#

Add the server to your config file, located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:

JSON

{  "mcpServers": {    "banksync": {      "url": "https://mcp.banksync.io",      "headers": {        "X-API-Key": "bsk_your_api_key_here"      }    }  }}

Claude Desktop also supports a one-click Desktop Extension: download the BankSync .mcpb bundle from the Claude Desktop setup page and open it with Claude Desktop; you will be prompted for your API key during installation.

Cursor#

Add the same JSON to .cursor/mcp.json in your project root (per-project) or ~/.cursor/mcp.json (global):

JSON

{  "mcpServers": {    "banksync": {      "url": "https://mcp.banksync.io",      "headers": {        "X-API-Key": "bsk_your_api_key_here"      }    }  }}

Other clients#

ChatGPT, Windsurf, VS Code Copilot, Gemini CLI, Zed, Warp, n8n, LibreChat, and 30+ other agents are supported, each with its own config quirks (some use serverUrl instead of url, some use OAuth instead of an API key). Per-client setup guides live at /docs/mcp/connect-an-agent.

Alternative: the npx bridge for stdio-only clients#

Some older clients only speak the stdio transport and cannot call a remote HTTP server directly. For those, BankSync publishes @banksync/mcp, a small npm package that runs locally and bridges stdio to the remote server. It requires Node.js:

JSON

{  "mcpServers": {    "banksync": {      "command": "npx",      "args": ["-y", "@banksync/mcp"],      "env": {        "BANKSYNC_API_KEY": "bsk_your_api_key_here"      }    }  }}

The bridge reads your key from the BANKSYNC_API_KEY environment variable and forwards every call to https://mcp.banksync.io. Prefer the direct remote configuration whenever your client supports it; the bridge exists only for compatibility.

Security and scope guidance#

Least privilege

Give the key only the scopes the agent needs. Read-only agents get read-only keys.

Server-side enforcement

Scopes are enforced by BankSync, not by the client, so a misbehaving agent cannot exceed its key.

Rotate and revoke

Set key expirations, and revoke a key instantly from Settings > Developers if it leaks.

One key per agent

Use a separate key per client so you can see, limit, and revoke each agent independently.

Review what you share

Anything the key's scopes allow, the AI assistant can read and act on. Before connecting an agent, decide whether it really needs write access, and remember that conversations with third-party AI services are processed by those services.

Confirm it worked#

Ask your agent something simple that requires a tool call, such as "List my workspaces" or "What banks are connected?". A correct setup returns real data from your workspace. If the client has an MCP status view (like /mcp in Claude Code), check that the banksync server shows as connected with tools available.

Troubleshooting#

Common issues

401 or "invalid API key": check the key starts with bsk_, has no stray whitespace, and has not been revoked or expired. Plan-gating error: MCP requires Standard or above; Free and Starter keys are rejected. Tools fail with a permissions error: the key is missing the scope for that resource, so create a key with the right scopes. 429 rate limited: you are over your plan's per-minute MCP rate (15/30/300 on Standard/Professional/Business); back off and retry, or upgrade. Client cannot connect at all: confirm it supports Streamable HTTP remote servers, or fall back to the npx @banksync/mcp stdio bridge.

API keys: create, scope, and revoke the bsk_ keys the MCP server authenticates with.
REST API guide: the same data over plain HTTP if you are building software rather than connecting an agent.
Changing your plan: MCP access and rate limits are set by your plan tier.
Connect an agent: step-by-step setup for every supported MCP client.