--- title: "MCP Server Guide" description: "Connect AI agents like Claude Code, Claude Desktop, and Cursor to your BankSync data through the remote MCP server at mcp.banksync.io." section: "MCP" canonical: "https://banksync.io/docs/mcp/overview" --- 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. [![Creating the API key an MCP client needs: opening Settings, the Developer section, creating a key named Production MCP Server with feeds and banks scopes, and copying the one-time bsk\_ key that works for both the REST API and MCP clients.](https://cdn.banksync.io/videos/api-keys-and-mcp.poster.a4bc2ee6ace134e3.png)](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4) [Watch: Creating the API key an MCP client needs: opening Settings, the Developer section, creating a key named Production MCP Server with feeds and banks scopes, and copying the one-time bsk\_ key that works for both the REST API and MCP clients.](https://cdn.banksync.io/videos/api-keys-and-mcp.76edc41d298a567a.mp4) 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](/docs/account-billing/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** 1. **Open Settings > Developers** — In your workspace, open Settings, then the Developers section under the Workspace group. The API Keys panel lists existing keys. 2. **Create a key** — Click Create Key, name it (for example "Claude Desktop"), and pick an expiration. 3. **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. 4. **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](/docs/api/api-keys). ![The Create API Key dialog with a key name filled in and per-resource read and write permission scopes selected.](https://cdn.banksync.io/screenshots/api/create-key-filled.30cd75c657c6d210.png "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: ```bash 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.' ## Related guides - [API keys](/docs/api/api-keys): create, scope, and revoke the `bsk_` keys the MCP server authenticates with. - [REST API guide](/docs/api/rest-api): the same data over plain HTTP if you are building software rather than connecting an agent. - [Changing your plan](/docs/account-billing/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.