Connect the BNBCalc MCP server

Connect BNBCalc to Claude, ChatGPT, Claude Code, Cursor or VS Code, one step at a time. Claude and ChatGPT need no code and nothing to install. Then ask a free question to check it works, and find fixes for the errors people hit most.

BNBCalc MCP serverBNBCalc MCP reference

Before you start

  1. 1

    You need a BNBCalc account and an AI app such as Claude or ChatGPT. You don't need a key or any code: the first time your app connects, a BNBCalc page opens, so sign in and click Allow.

  2. 2

    Free tools work right away. For paid tools, open Settings → API & MCP and start the API subscription: checkout asks for a card, but there's no monthly fee and nothing is charged until you make paid calls. The same subscription covers the REST API.

  3. 3

    Pick your app below and follow its steps in order. Not a developer? Use Claude or ChatGPT: there is nothing to install. Every app uses the same server address: https://atlas.bnbcalc.com/mcp.

The sign-in page names the app that's connecting and asks to share your basic profile and email. Your password stays with BNBCalc; the app only gets an access token for the MCP server.

Claude

  1. 1

    Open Claude on the web or in the desktop app, go to Settings and open Customize.

    Claude's Settings window with Customize selected and the Connectors tab open
  2. 2

    On the Connectors tab, click Add, then Add custom connector.

    Claude's Customize settings on the Connectors tab, with the Add menu open on Add custom connector
  3. 3

    Type BNBCalc as the name, paste this address into the MCP server URL box and click Continue.

    Custom connector URL

    https://atlas.bnbcalc.com/mcp
    Claude's Add custom connector form with BNBCalc as the name and the BNBCalc server address as the MCP server URL
  4. 4

    Claude checks the server and shows its sign-in options. Leave them as they are and click Add.

    Claude's Add custom connector options for BNBCalc, with Sign in now selected and the Add button
  5. 5

    Claude shows that you're not connected to BNBCalc yet. Click Connect.

    The BNBCalc connector in Claude's settings before connecting, with the Connect button
  6. 6

    A BNBCalc page opens: sign in and click Allow. Back in Claude, the connector now lists BNBCalc's tools.

    The BNBCalc connector in Claude's settings, connected, with its tools listed
  7. 7

    Start a new chat and ask the free question under Check it works. Claude asks before it uses a BNBCalc tool: click Allow once. BNBCalc now works in Claude on the web, in Claude Desktop and in the mobile app.

    A Claude chat where BNBCalc answers a DSCR question

On a Team or Enterprise plan, an owner may need to add the connector first.

ChatGPT

  1. 1

    Open ChatGPT and go to Settings, then Plugins, and click Browse directory. The Plugins page opens.

    ChatGPT's Plugins page with the Add button in the top right corner
  2. 2

    Click Add, then Add custom MCP server.

    ChatGPT's Plugins page with the Add menu open on Add custom MCP server
  3. 3

    Type BNBCalc as the name and paste this address under Connection, in the Server URL box. Leave Authentication on OAuth.

    Custom connector URL

    https://atlas.bnbcalc.com/mcp
  4. 4

    Tick I understand and want to continue, then click Create as a plugin.

    ChatGPT's Add custom MCP server form with BNBCalc as the name, the BNBCalc server address, OAuth authentication and the box ticked
  5. 5

    ChatGPT shows a Connect BNBCalc window. Click Connect BNBCalc.

    ChatGPT's Connect BNBCalc window with the Connect BNBCalc button
  6. 6

    The BNBCalc sign-in page opens. Sign in, then click Allow.

    The BNBCalc sign-in page, with Continue with Google and an email address box
  7. 7

    Start a new chat, click the plus button next to the message box and choose BNBCalc. Then ask the free question under Check it works.

    ChatGPT's message box with the plus menu open and BNBCalc in the list

ChatGPT renames its menus from time to time. If yours look different, look for a way to add a custom MCP server, plugin or connector. Some accounts need Developer mode turned on in Settings first.

Claude Code

  1. 1

    Open a terminal and run this command. --scope user adds BNBCalc to every project; without it, Claude Code adds the server to the current project only.

    Terminal

    claude mcp add --transport http --scope user bnbcalc https://atlas.bnbcalc.com/mcp
  2. 2

    Start Claude Code and type /mcp.

  3. 3

    Pick bnbcalc and choose Authenticate. A BNBCalc page opens: sign in and click Allow.

  4. 4

    Run claude mcp list to see bnbcalc connected.

Cursor

  1. 1

    Click Add to Cursor under the code and confirm in Cursor. Or paste this into ~/.cursor/mcp.json to use BNBCalc in every project, or into .cursor/mcp.json inside one project.

    ~/.cursor/mcp.json

    {
      "mcpServers": {
        "bnbcalc": {
          "url": "https://atlas.bnbcalc.com/mcp"
        }
      }
    }
    Add to Cursor
  2. 2

    Open Cursor's MCP settings and find bnbcalc.

  3. 3

    Click its button to sign in. A BNBCalc page opens: sign in and click Allow.

  4. 4

    Check that bnbcalc shows its tools. If it won't connect, the MCP Logs output says why.

VS Code

  1. 1

    Click Install in VS Code under the code. Or run the MCP: Open User Configuration command and paste this in; the same entry works in a project's .vscode/mcp.json.

    .vscode/mcp.json

    {
      "servers": {
        "bnbcalc": {
          "type": "http",
          "url": "https://atlas.bnbcalc.com/mcp"
        }
      }
    }
  2. 2

    Run MCP: List Servers and start bnbcalc.

  3. 3

    When VS Code asks to sign in to BNBCalc, allow it, then sign in and click Allow.

  4. 4

    Open Copilot's agent mode and check that BNBCalc's tools appear.

Connect with your API key

Use this when an app or script can't open a sign-in page and can only send a fixed header. Otherwise, signing in above is simpler.

  1. 1

    Open Settings → API & MCP in BNBCalc and start the API subscription if you haven't yet. There's no monthly fee.

  2. 2

    Create a key and copy it right away: it is shown in full only once.

  3. 3

    Paste the key where these configs say YOUR_API_KEY. It is sent in the x-bnbcalc-api-key header.

    Terminal

    claude mcp add --transport http --scope user bnbcalc \
      https://atlas.bnbcalc.com/mcp \
      --header "x-bnbcalc-api-key: YOUR_API_KEY"
  4. 4

    Restart your app, then ask the free question under Check it works.

Claude Desktop can't send a custom header on its own, so its config runs a small bridge, mcp-remote, through npx; install Node.js 18 or newer first. Open the config from Settings → Developer → Edit Config, and keep no space after the colon in x-bnbcalc-api-key:${BNBCALC_API_KEY}, since a space breaks on Windows. Then quit Claude Desktop completely and open it again.

This is the same key the REST API uses. One key works in several apps; if you regenerate it, update each app that uses it, and keep files with a key out of version control.

Other MCP apps

Any app that connects to a remote server over streamable HTTP works, by signing in with BNBCalc or by sending your BNBCalc API key in a custom header. The server takes POST requests and keeps no sessions, so apps that only use the older SSE connection won't work. Cline, for example, needs "type": "streamableHttp" in its config.

Check it works

Ask a free question first, such as “What's my BNBCalc MCP usage this month?” or “Calculate the DSCR on $36,000 of operating income and a $400,000 loan at 7% over 30 years.” If BNBCalc answers, you're connected, and nothing has been charged.

See your usage and cost

Open Settings → API & MCP. The usage card has an API and MCP switch: choose MCP to see each tool's successful calls, units and cost for the billing period. Only successful calls are billed.

Common errors

The server's error message names the cause. These are the ones people hit most:

Missing MCP credentials. Connect with OAuth or provide your API key in x-bnbcalc-api-key
Finish connecting in your app; in Claude Code, type /mcp and choose Authenticate. With a key, check the header is spelled x-bnbcalc-api-key.
Invalid or expired OAuth access token
The app's sign-in expired or was revoked. Connect again from the app, or remove BNBCalc and add it back.
No BNBCalc account is linked to this sign-in yet. Sign in once at https://www.bnbcalc.com, then reconnect.
Your sign-in has no verified email, so BNBCalc couldn't set up your account from it. Sign in once on the BNBCalc website with the same email or Google account, then connect again.
You are trying to call a paid BNBCalc tool (…), which needs an API & MCP subscription on BNBCalc
Free tools work without a subscription. Subscribe to API access in Settings → API & MCP (there's no monthly fee), then ask again; you don't need to reconnect.
Invalid API key
Check that you copied the whole key from Settings → API & MCP. If the key was regenerated or deleted, put the new one in your config.
API access requires an active BNBCalc API subscription
MCP access requires an active BNBCalc API subscription
Keys need an API subscription, which covers MCP: subscribe in Settings → API & MCP.
BNBCalc access is suspended after a failed payment. Update your payment method under Settings → API & MCP on the BNBCalc website.
API key is suspended or inactive
The subscription ended or a payment failed twice. Subscribe again or pay the open invoice, and the same key works again.
Daily data limit reached for this API key. It resets at 00:00 UTC.
Wait until 00:00 UTC. The limit is shared with the REST API, and failed lookups count too.
AI request rate limit exceeded
Too many AI requests in flight (max 2 concurrent)
Wait a minute, and run AI comps or AI expense estimates two at a time.
External API request timed out; it may still complete. Do not automatically retry.
Don't retry yet: the call may still finish, and bill. Ask the assistant to list your saved analyses first.
Check the server status More fixes in the Help Center