# Connect Bilance MCP: steps for AI agents

A user asked you to connect Bilance, their personal finance app. These are the steps. The page for people is https://www.bilanceapp.com/help/connect-ai-apps.

- Server URL: `https://mcp.bilanceapp.com/mcp`. Name it `bilance`.
- Remote HTTP (streamable HTTP) with OAuth. There is no API key, token or header to set.
- `bilanceapp.com/mcp` is the help page, not the server. Don't add it.

You do everything except one step: the user signs in to Bilance in their browser and taps **Allow access**. Don't ask for their password, don't read token stores or keychains, and don't decode tokens.

Work in this order: check, add, sign in, verify. Do the steps yourself instead of handing the user a list of commands.

## Claude Code

1. Check: `claude mcp list`. Look for `bilance` and `plugin:bilance:bilance` (the Bilance plugin) with the URL above.
   - `✔ Connected`: it's already connected. Go to step 4 and check whose data it is. To use another account, run `claude mcp logout <name>` and go to step 3.
   - `! Needs authentication`: go to step 3 with that name.
   - Both entries: keep one and remove the other (see Remove). They can be signed in to different accounts.
   - Nothing: go to step 2.
2. Add: `claude mcp add --transport http --scope user bilance https://mcp.bilanceapp.com/mcp`
3. Sign in: `claude mcp login bilance` (or `claude mcp login plugin:bilance:bilance`). It opens the browser and waits until the user approves.
   - It needs an interactive terminal. Without one it stops with `stdin isn't a terminal`. Then run it under `script` so it gets one: on macOS `script -q /dev/null claude mcp login bilance`, on Linux `script -q -c "claude mcp login bilance" /dev/null`.
   - Run it in the background, because it waits for the browser. Tell the user to approve in the browser window that opened. If no window opened, give them the URL it printed, copied exactly.
   - Wait for it to finish before you end your turn, then check `claude mcp list` again.
   - If you can't run it, ask the user to run `claude mcp login bilance` in their own terminal.
4. Verify: `claude mcp list` shows `bilance: https://mcp.bilanceapp.com/mcp (HTTP) - ✔ Connected`. Bilance tools load when a session starts, so this session may not have them. To check now, run `claude -p "Call get_finance_context and tell me connectedAccount.email" --allowedTools mcp__bilance__get_finance_context` (for the plugin: `mcp__plugin_bilance_bilance__get_finance_context`). Tell the user "Connected to Bilance as <email>". Then tell them to start a new session to use Bilance.

Remove: `claude mcp logout bilance`, then `claude mcp remove bilance`. The plugin can't be removed with `claude mcp remove`. Use `claude plugin uninstall bilance@bilance`.

## Codex (CLI and app)

1. Check: `codex mcp list`. Look for `bilance` with the URL above.
   - Auth `OAuth`: it's already signed in. Go to step 4. To use another account, run `codex mcp logout bilance` and go to step 3.
   - Auth `Not logged in`: go to step 3.
   - Nothing: go to step 2.
2. Add: `codex mcp add bilance --url https://mcp.bilanceapp.com/mcp`. This usually starts the sign-in right away, as in step 3. If it prints "Run `codex mcp login bilance` to login", do step 3.
3. Sign in: `codex mcp login bilance`. It opens the browser and waits until the user approves, then prints `Successfully logged in to MCP server 'bilance'`. It needs network access. If no browser window opened, give the user the URL it printed, copied exactly. Keep waiting for the command to finish before you end your turn. If your turn ends first, the command may stop and the approval goes nowhere.
4. Verify: `codex mcp list` shows Auth `OAuth`. Bilance tools load when a session starts. Ask the user to start a new Codex session and ask about their money. That session should call `get_finance_context` first and say which account it is connected to.

Remove: `codex mcp logout bilance`, then `codex mcp remove bilance`. If that says `No MCP server named 'bilance' found` while `codex mcp list` still shows it, it comes from the Bilance plugin. Remove that with `codex plugin remove bilance@bilance`.

## Claude (claude.ai, desktop and mobile apps)

You can't add a connector from a chat. Give the user these steps:

1. Open claude.ai in a browser or the Claude desktop app.
2. Choose **Customize** in the sidebar and open **Connectors**.
3. Choose **Add**, then **Add custom connector**.
4. Name: *Bilance*. URL: `https://mcp.bilanceapp.com/mcp`. Choose **Continue**.
5. Sign in to Bilance and tap **Allow access**.
6. Start a new chat and ask about their money.

If a Bilance connector is already there, they should use it. To switch accounts, they disconnect it and connect again.

## ChatGPT

You can't add an app from a chat. Give the user these steps:

1. Open chatgpt.com in a browser or the ChatGPT desktop app.
2. Add a custom MCP server. Depending on the account, it's under **Plugins** or **Apps** in the settings.
3. Name: *Bilance*. URL: `https://mcp.bilanceapp.com/mcp`.
4. Confirm the warning and create it. Sign in to Bilance and tap **Allow access**.
5. In a chat, type **@Bilance** and ask the question.

## Cursor

Add Bilance to `~/.cursor/mcp.json`. Keep any servers already there:

```json
{
  "mcpServers": {
    "bilance": { "url": "https://mcp.bilanceapp.com/mcp" }
  }
}
```

Then the user opens Cursor Settings, finds `bilance` in the MCP list and signs in.

## Gemini (gemini.google.com)

You can't add a connector from a chat. Give the user these steps, on a computer:

1. Open gemini.google.com in a browser.
2. Open **Customize** → **Connectors** and click **+ Custom**.
3. Paste `https://mcp.bilanceapp.com/mcp` and click **Next**.
4. Sign in to Bilance and click **Allow access**.
5. In a chat, ask the question.

Not every Gemini account has **+ Custom** yet, and the Gemini phone app doesn't have it. If it's missing, the user can connect Claude, ChatGPT or Gemini CLI instead.

## Gemini CLI

1. Check: `gemini mcp list`.
2. Add: `gemini mcp add --scope user --transport http bilance https://mcp.bilanceapp.com/mcp`. Without `--scope user` it is added to the current project only.
3. Sign in: the user runs `/mcp auth bilance` inside Gemini CLI. There is no command for it outside Gemini CLI.

Remove: `gemini mcp remove --scope user bilance`.

## Other apps

Any app that supports remote MCP servers with OAuth works. Add `https://mcp.bilanceapp.com/mcp` with no headers or API key, and let the app start the sign-in.

## Verify

Call `get_finance_context` first. Its `connectedAccount.email` is the Bilance account this connection is signed in to. Tell the user "Connected to Bilance as <email>". If it's the wrong account, sign out and sign in again (`claude mcp logout bilance` or `codex mcp logout bilance`, then the sign-in step). If `connectedAccount` is missing, name the accounts you see instead and ask the user if this is their Bilance.

## When something fails

- Sign-in fails with `server_error` or "An unexpected error occurred": run the sign-in command once more. Ask the user to approve in the window it opens, not to copy the link to another browser window. If it fails twice, stop and tell the user to email help@bilanceapp.com with the time it happened.
- The sign-in URL goes to `vast-citadel-20.authkit.app` and then back to `localhost` or `127.0.0.1` on the user's computer. That's normal: the AuthKit page is Bilance's sign-in, and the local address is the CLI receiving the result.
- `Needs authentication` or `Not logged in` after the user approved: run the sign-in again. The approval may have gone to an older sign-in link.
- "An active Bilance subscription is required": the account has no active subscription. The user can subscribe or restore purchases in the Bilance app.
- "Bilance had an internal error (reference mcp-...)": the problem is on Bilance's side, not the connection or the sign-in. Don't reconnect or retry. Tell the user to email help@bilanceapp.com with the reference.
- "Bilance data service is temporarily unavailable": try once more after a minute. If it keeps happening, stop retrying and tell the user to email help@bilanceapp.com with the time and the AI app they use.
- Entries with other names or `localhost` URLs, such as `bilance-local`, are not this server. Leave them alone.

Users can see and disconnect their AI apps in the Bilance app: **Account** → **Settings** → **Connected AI apps**. Removing the server from your config doesn't disconnect it there.