bankmcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nils Smed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+# BankMCP™
+
+**Your AI now reads your bank.** Ask it anything about your accounts. Read-only, self-hosted, one user. Standard MCP; tested with Claude and Ollama.
+
+BankMCP™ is not a bank. It is a small open-source server you host yourself
+(package name `bank-mcp`). It connects to your banks
+through [Enable Banking](https://enablebanking.com), which wraps 2,700+
+European banks in one PSD2 API, and exposes them to any MCP client as a
+connector. Read-only, no payments, no third party holding your data.
+
+> "Has the invoice from Acme been paid?" · "What did we spend on groceries in
+> August?" · "Which subscriptions am I paying for, and what do they cost per
+> year?" · "Tell me when my balance drops below 5,000."
+
+## How it works
+
+```
+Your assistant ──OAuth──▶ your BankMCP™ server ──JWT──▶ Enable Banking ──PSD2──▶ your bank
+```
+
+- **Your assistant** (Claude, ChatGPT, Cursor, or any MCP client) talks to
+  your server as a connector. You sign in once with a password; tokens handle
+  the rest.
+- **Your server** holds the Enable Banking application key, the bank consents
+  and your account ids. It does not store balances or transactions and sends no
+  telemetry.
+- **Enable Banking** is the licensed provider. You log in at your bank's own
+  site to approve access; nobody sees your bank credentials.
+
+## Setup
+
+Two ways to run it. Both need a free Enable Banking account and about ten
+minutes.
+
+- **On your own machine** for Claude Desktop, Claude Code, Cursor and other
+  desktop MCP clients. Nothing to deploy, no password.
+- **On a small server** when you want it in claude.ai or on your phone.
+
+### On your own machine
+
+Requires [Node 24](https://nodejs.org) or newer. Add BankMCP™ to your client:
+
+Claude Code:
+
+```bash
+claude mcp add bankmcp -- npx -y bankmcp
+```
+
+Claude Desktop: download
+[bankmcp.mcpb](https://github.com/noskillish/bankmcp/releases/latest/download/bankmcp.mcpb)
+and open it; Claude Desktop installs it as an extension. Or add it by hand in
+`claude_desktop_config.json`:
+
+```json
+{ "mcpServers": { "bankmcp": { "command": "npx", "args": ["-y", "bankmcp"] } } }
+```
+
+Cursor and others: the same command, `npx -y bankmcp`, as a stdio server.
+
+Then ask your assistant anything about your bank. It will answer with a
+localhost address. Open it: the setup page lists the values to register an
+application at Enable Banking, then takes the application id and the key file.
+Your browser will warn once about the certificate on localhost, which the
+server made for itself because Enable Banking requires https for the bank
+redirect. Continue past it. Say "connect my bank" and log in at your bank.
+
+State lives in `~/.bankmcp`. Delete the folder to forget everything.
+
+### On a server
+
+#### 1. Deploy
+
+Any container host works. The server needs a persistent volume at `/data`
+and a public https address; it asks you for everything else in the browser.
+
+**Railway:** New Project, Deploy from GitHub repo, pick this repo. Add a
+volume mounted at `/data` and generate a domain (Settings, Networking, port
+8080). The Dockerfile and [railway.json](railway.json) are picked up
+automatically, and the server learns its own address from Railway.
+
+**Docker Compose on your own box:** `docker compose up -d`, then put a TLS
+terminator in front (Caddy needs two lines:
+`YOUR-HOST { reverse_proxy localhost:8080 }`) and set `BASE_URL` to the
+public address. Fly.io works like Railway: volume at `/data`, the app name
+gives the address.
+
+Open the address. A fresh server shows a setup page.
+
+#### 2. Register an Enable Banking application
+
+The setup page lists the exact values Enable Banking's form asks for: the
+redirect URL, a description for the consent screen, and the privacy and
+terms URLs, all pointing at your server. At
+<https://enablebanking.com/cp/applications> create an application with them:
+
+- Environment: **Production** for your real accounts, **Sandbox** for test
+  data (see *Going live* below for the production rules).
+- Keep "generate private key" selected. A `.pem` file downloads once when you
+  save; that is the key. The application id (a UUID) is shown after saving.
+
+#### 3. Finish setup
+
+Back on the setup page: paste the application id, choose the `.pem` file, pick
+a password of twelve characters or more. Everything is stored on the volume,
+and the page turns into a status page showing the connector URL for your
+assistant.
+
+Prefer configuration by environment? Set these and the setup page does not
+appears:
+
+| Variable | Value |
+|---|---|
+| `EB_APP_ID` | the application id |
+| `EB_PRIVATE_KEY` | the `.pem` contents, base64: `base64 -i app.pem \| tr -d '\n'` |
+| `ADMIN_PASSWORD_HASH` | output of `npm run hash-password` (or set `ADMIN_PASSWORD`) |
+| `BASE_URL` | `https://YOUR-HOST` (Railway and Fly set this for you) |
+| `DEFAULT_COUNTRY` | your country code, e.g. `DK` |
+| `APP_NAME` | optional, the name shown on the sign-in and status pages (default `BankMCP™`) |
+
+Optional: `NOTIFY_WEBHOOK_URL` for watch notifications and sign-in alerts (a
+Slack incoming webhook works). Full list in [.env.example](.env.example).
+`npm run check` verifies a configuration from a terminal.
+
+#### 4. Add the connector in your assistant
+
+In claude.ai (or the desktop app): **Settings → Connectors → Add custom
+connector**. Name it `BankMCP™`, paste `https://YOUR-HOST/mcp`, save, then click
+**Connect**. Your server shows a password page; enter the admin password. That
+is the only login you will do.
+
+In Claude Code:
+
+```bash
+claude mcp add --transport http bank https://YOUR-HOST/mcp
+```
+
+then run `/mcp` inside Claude Code to sign in.
+
+Other MCP clients (ChatGPT, Mistral Le Chat, Cursor, VS Code) work the same
+way: add the URL as a remote MCP server, sign in with the password. Tested
+with Claude, Claude Code and Ollama; the others follow the same standard.
+A client whose domain is not in `ALLOWED_REDIRECT_HOSTS` needs adding there.
+
+#### 5. Connect your bank
+
+In your assistant, say **"connect my bank"** (or use the `connect-bank` prompt). It
+looks up your bank, gives you a link, you log in at the bank and approve, and
+the accounts appear. Consents last up to 180 days; you are told when one
+is about to expire and the same conversation renews it.
+
+Give accounts labels ("Everyday", "Joint expenses", "Mortgage") when it
+suggests them. Every tool accepts labels instead of ids.
+
+## Going live with your own accounts
+
+Enable Banking's production environment normally requires a contract, but it
+has a **restricted mode** for accessing *your own* accounts, explicitly allowed
+for individual non-commercial use. After registering a Production application:
+
+1. On the (Inactive) application click **Activate by linking accounts**.
+2. Log in at your bank and approve. Repeat for each bank you want.
+3. The application becomes active and the API returns only the accounts you
+   linked this way.
+
+Read the *Restriction of Use* section of Enable Banking's
+[Terms of Service](https://enablebanking.com/terms-of-service/) before you
+rely on it: restricted mode is for your own accounts, not for offering a
+service to others. This project does not change those terms.
+
+## What you get
+
+**Tools** (all read-only):
+
+| Tool | What it does |
+|---|---|
+| `list_banks`, `start_consent`, `consent_status`, `disconnect_bank` | connect and manage banks |
+| `list_accounts`, `set_account_label` | accounts with booked balances; your own names for them |
+| `get_balances` | booked and available balance for one account |
+| `get_transactions` | signed amounts, one counterparty, one description; paginated |
+| `create_watch`, `list_watches`, `delete_watch`, `check_watches` | background rules with webhook notifications |
+
+**Prompts**: `connect-bank`, `monthly-summary`, `build-budget`,
+`subscription-audit`, `unusual-transactions`.
+
+**Watches** run on the server. Rules: balance below or above an amount, a
+single debit over an amount, an incoming or outgoing payment matching a name,
+and "tell me if this payment has not arrived by this date". Accounts are
+checked at most four times a day, the PSD2 limit for unattended access.
+Notifications go to `NOTIFY_WEBHOOK_URL` as a Slack message or a JSON POST.
+
+Enable Banking's own webhooks cover payment initiation only, so account data
+is polled. There is no way around that under PSD2.
+
+## Claude Code plugin
+
+The repository is also a Claude Code plugin marketplace. The `bank` plugin
+bundles the connector entry and a skill that encodes how to work with the
+data: an account map, categorisation rules, the monthly review format and when
+to create watches.
+
+Point it at your server, then install:
+
+```bash
+export OPENBANK_URL=https://YOUR-HOST/mcp   # put this in your shell profile
+```
+
+```
+/plugin marketplace add noskillish/bankmcp
+/plugin install bank@bank
+```
+
+Then `/mcp`, select `bank`, Authenticate, and enter your password. No
+organisation admin is involved; plugins are per user.
+
+The skill lives at [plugin/skills/bank/SKILL.md](plugin/skills/bank/SKILL.md).
+Copy it into your own skills to fill in the account map and your merchant
+rules. The server stays generic; your rules stay yours.
+
+## Local models (experimental)
+
+The server does not care which model asks. `npm run chat` bridges an
+[Ollama](https://ollama.com) model to the same tools over stdio, so no AI
+vendor sees a transaction:
+
+```bash
+ollama pull qwen3:8b
+npm run chat -- "what's my balance?"
+```
+
+Measured on a MacBook Air with 24 GB: correct per-account balances, a wrong
+total, ten minutes per answer. An 8B model is not yet trustworthy with money;
+a 30B-class model on a machine with a real GPU is where it gets useful. Any
+MCP client with tool calling (LM Studio, Goose, Jan) can also point at
+`node src/stdio.ts` directly. Enable Banking still sits between you and the
+bank either way; that part is regulated and unavoidable.
+
+## Security notes
+
+- The server is a complete OAuth 2.1 authorization server with one user.
+  Discovery, dynamic client registration and PKCE come from the MCP SDK;
+  tokens are stored hashed; five wrong passwords lock an address out for
+  fifteen minutes.
+- State is one JSON file in `DATA_DIR`: consents, account ids, watches (with
+  the ids of transactions that already fired) and OAuth tokens. Balances and
+  transactions are not written to disk. Your assistant keeps the
+  conversation as any chat does, and a watch notification carries the matched
+  transaction to your webhook. Back the file up if you care about not
+  re-consenting; delete it to forget everything.
+- Only clients that redirect back to a known MCP client domain (Claude,
+  ChatGPT, Mistral, Cursor, VS Code) or localhost can register
+  (`ALLOWED_REDIRECT_HOSTS`), which stops a phishing link from routing your sign-in to
+  another site. Using a client not on the list? Add its domain. The sign-in page also names the host you will
+  be sent back to.
+- Anyone with the admin password can read your accounts. Use a long one.
+  Every successful sign-in is logged and, if `NOTIFY_WEBHOOK_URL` is set,
+  sent to you as a message. A sign-in you did not make is your alarm.
+- Changing `ADMIN_PASSWORD_HASH` (or `ADMIN_PASSWORD`) and restarting logs
+  every client out. That is the kill switch. Revoking the consents at your
+  bank, or deleting the state file, is the step beyond it.
+- There are no payment tools. Payments need a licensed PISP and a very
+  different security model, so they are out of scope.
+
+## Commands
+
+```bash
+npm start              # http server (reads env from the environment)
+npm run dev            # same, with reload and .env
+npm run check          # verify config and the Enable Banking application
+npm run hash-password  # produce ADMIN_PASSWORD_HASH
+npm run watch -- --force   # run all watches once, print what fired
+npm test               # unit tests (node:test)
+npm run typecheck
+sh scripts/build-mcpb.sh   # Claude Desktop bundle → dist/bankmcp.mcpb
+```
+
+Requires Node 24 or newer (runs TypeScript directly, no build step).
+
+## Layout
+
+```
+src/server.ts         Express: /mcp behind OAuth, OAuth endpoints, /callback, status page
+src/auth.ts           single-user OAuth provider, password login page
+src/mcp.ts            McpServer factory (tools + prompts + instructions)
+src/tools.ts          the MCP tools
+src/prompts.ts        the MCP prompts
+src/watcher.ts        background rule checks and notifications
+src/enablebanking.ts  JWT signing and a thin typed API client
+src/store.ts          the JSON state file
+src/data.ts           shaping balances and transactions for an assistant
+src/stdio.ts          local entry point (stdio, used by `npx bankmcp`)
+src/local.ts          localhost https server for setup and the bank redirect in local mode
+src/app.ts            the Express app shared by both modes
+src/cli.ts            check, hash-password, watch
+plugin/               Claude Code plugin with the bank skill
+```
+
+## What this is, and is not
+
+BankMCP™ is software, not a service. There is no hosted BankMCP™, no account to sign
+up for, and nobody but you handles your server, your key or your bank
+consents. Each person who uses it deploys their own copy and is the sole
+operator of that copy: they register their own Enable Banking application,
+accept Enable Banking's terms themselves, and are responsible for their own
+hosting, password and security.
+
+The authors publish the code and nothing else. They do not run any instance
+for others, receive no data, and are not affiliated with Enable Banking,
+Anthropic or any bank. BankMCP™ is not a bank, does not hold money, and gives no
+financial advice.
+
+**Use at your own risk.** If you deploy it, you own that deployment and its
+security. The software is provided as is, without warranty of any kind, and
+the authors accept no liability for how it is used or for any loss that
+follows. MIT licence below.
+
+## License
+
+MIT

package/bin/bankmcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Runs BankMCP™ locally over stdio for an MCP client. Requires Node 24 or newer.
+const [major] = process.versions.node.split(".").map(Number);
+if (major < 24) {
+  console.error(`BankMCP needs Node 24 or newer (you have ${process.versions.node}).`);
+  process.exit(1);
+}
+await import("../src/stdio.ts");

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "bankmcp",
+  "version": "0.1.0",
+  "description": "BankMCP™: self-hosted, read-only MCP server that lets any AI assistant (Claude, ChatGPT, Mistral, Cursor, or a local model) answer questions about your own bank accounts via open banking (Enable Banking, PSD2)",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "start": "node src/server.ts",
+    "dev": "node --watch --env-file=.env src/server.ts",
+    "stdio": "node --env-file=.env src/stdio.ts",
+    "check": "node --env-file-if-exists=.env src/cli.ts check",
+    "hash-password": "node src/cli.ts hash-password",
+    "watch": "node --env-file-if-exists=.env src/cli.ts watch",
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "chat": "node --env-file-if-exists=.env scripts/local-chat.ts",
+    "local": "node bin/bankmcp.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "express": "^5.2.1",
+    "selfsigned": "^5.5.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  },
+  "bin": {
+    "bankmcp": "bin/bankmcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugin",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "bank",
+  "version": "0.1.0",
+  "description": "BankMCP™: work with your own bank accounts through an bank-mcp (Enable Banking, open banking) connector: account mapping, categorisation rules and the monthly review format.",
+  "author": { "name": "Nils Smed" },
+  "homepage": "https://github.com/noskillish/bankmcp",
+  "license": "MIT",
+  "keywords": ["banking", "personal-finance", "psd2", "enable-banking", "mcp"]
+}

package/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "bank": {
+      "type": "http",
+      "url": "${OPENBANK_URL:-http://localhost:8080/mcp}"
+    }
+  }
+}

package/plugin/skills/bank/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: bank
+description: Answer questions about the user's own bank accounts and money using the bank MCP tools (list_accounts, get_balances, get_transactions, watches). Use whenever the user asks about balances, spending, income, subscriptions, whether a payment arrived, or wants a monthly review. Encodes the account map and categorisation rules so answers are consistent.
+---
+
+# bank
+
+You have read-only access to the user's own bank accounts through the `bank` MCP server. There are no payment tools.
+
+## Ground rules
+
+- Amounts are signed: negative is money out. Use the `booked` balance for totals and net worth. `available` can include an overdraft or a credit line, so a mortgage can show a positive `available` while `booked` is deeply negative.
+- Refer to accounts by their label. Run `list_accounts` once per conversation to see labels and uids. If an account has no label, suggest one and set it with `set_account_label`.
+- Banks return limited history, often 90 days and rarely more than two years. If a range comes back empty, say the bank returned nothing rather than assuming there was no activity.
+- Do not invent or "adjust" a balance or transaction. If the user asks for a number to look different than it is, decline and offer to explain the real one.
+- Keep answers short. Numbers in the account's currency, rounded to whole units unless cents matter.
+
+## Account map
+
+Fill this in for the user (or ask them to). Copy it into the user's own copy of this skill.
+
+| Label | Purpose | Treat as |
+|---|---|---|
+| Everyday | Salary in, cards and bills out | Personal spending |
+| Savings | Buffer | Personal, exclude from spending |
+| Joint expenses | Shared household costs, funded by fixed monthly transfers from each partner | Shared spending |
+| Housing | Mortgage payments and housing bills | Shared spending |
+| Mortgage | Loan | Liability, not spending |
+
+Transfers between the user's own accounts are not income or spending. Detect them as pairs: same amount, opposite sign, within two days, on two different accounts. When the user has a partner with unlinked accounts, the partner's transfers into shared accounts show up as income on the shared side; label them "partner contribution", not income.
+
+## Categorisation
+
+Use the counterparty first, then the description. Categories:
+
+income, transfer, housing, utilities, groceries, eating out, transport, subscriptions, shopping, health, kids, travel, insurance, fees, cash, other.
+
+Rules of thumb:
+- Recurring same-amount debits from a company: subscriptions (streaming, phone, gym, software) or utilities (power, water, heating, internet) or insurance.
+- Supermarket chains and grocers: groceries. Restaurants, cafés, takeaway apps: eating out.
+- Public transport, fuel, parking, ride hailing, tolls, bridge fees: transport.
+- Mortgage and rent: housing. Property tax and housing association fees: housing.
+- Pharmacies, doctors, dentists: health. Daycare, school, kids' clubs: kids.
+- Airlines, hotels, foreign card payments in a cluster: travel.
+- Card fee, interest, currency surcharge: fees.
+
+Add the user's own rules below as `pattern → category` lines and apply them before the rules of thumb:
+
+```
+# STRIPE PAYOUT → income (client invoices)
+# ACME INSURANCE → insurance
+```
+
+## Monthly review format
+
+1. Headline: income, spending, net, savings rate. One line.
+2. Spending by category, largest first, with share of total. Compare to the previous month if you fetched it.
+3. Ten largest single expenses with date, counterparty, account.
+4. Recurring items seen this month and their yearly cost.
+5. Two or three observations worth acting on. Concrete: "Eating out was 40% above the three-month average; three of the ten largest expenses were restaurants."
+
+## Watches
+
+Use `create_watch` when the user says "tell me when", "let me know if", "has X paid yet, keep an eye on it":
+
+- Waiting for a payment: `credit_missing_by` with `match` = payer name and `by_date` = due date. It notifies when the money arrives or when the date passes.
+- Cash floor: `balance_below` on the everyday account.
+- Fraud and surprises: `large_debit` with an amount around three times the usual biggest card payment.
+
+Notifications go to the server's webhook. If `create_watch` says no webhook is configured, tell the user to set NOTIFY_WEBHOOK_URL on the server; `check_watches` still works on demand.

package/src/app.ts

@@ -0,0 +1,176 @@
+// HTTP entry point: the MCP endpoint behind OAuth, the OAuth server itself,
+// the Enable Banking redirect target, and a status page.
+import { createHash } from "node:crypto";
+import express from "express";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { config, isConfigured, setupProblems } from "./config.ts";
+import { eb, EnableBankingError } from "./enablebanking.ts";
+import { store } from "./store.ts";
+import { SingleUserProvider } from "./auth.ts";
+import { connectedPage, failedPage, loginPage, privacyPage, setupPage, signInFailedPage, statusPage, termsPage } from "./pages.ts";
+import { applySetup, setupAvailable } from "./setup.ts";
+import { createServer, VERSION } from "./mcp.ts";
+import { startWatcher } from "./watcher.ts";
+
+export interface AppOptions {
+  /** Mount the OAuth server and the /mcp endpoint. Off in local (stdio) mode. */
+  remote: boolean;
+}
+
+export function createApp(opts: AppOptions) {
+  const log = (msg: string, extra?: unknown) => console.log(`[bank ${new Date().toISOString()}] ${msg}`, extra ?? "");
+
+  const app = express();
+  app.set("trust proxy", 1);
+  app.disable("x-powered-by");
+  app.use((_req, res, next) => {
+    res.set({
+      "X-Frame-Options": "DENY",
+      "X-Content-Type-Options": "nosniff",
+      "Referrer-Policy": "no-referrer",
+      "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+    });
+    next();
+  });
+
+  const baseUrl = new URL(config.baseUrl);
+  const mcpUrl = new URL("/mcp", baseUrl);
+  const provider = new SingleUserProvider(store(), {
+    onLogin: (e) => {
+      const who = e.clientName ? ` for ${e.clientName}` : "";
+      if (e.ok) {
+        log(`sign-in from ${e.ip}${who}`);
+        notify(`${config.appName}: new sign-in from ${e.ip}${who}. If this was not you, change ADMIN_PASSWORD now; that logs every client out.`);
+      } else {
+        log(`failed sign-in from ${e.ip}${who} (${e.reason})`);
+      }
+    },
+  });
+
+  // Changing the admin password logs every client out.
+  function rememberPasswordFingerprint(): void {
+    const secret = config.adminPasswordHash || config.adminPassword;
+    if (!secret) return;
+    const fingerprint = createHash("sha256").update(secret).digest("hex");
+    if (store().data.oauth.password_fingerprint && store().data.oauth.password_fingerprint !== fingerprint) {
+      provider.revokeAll();
+      log("admin password changed: all tokens revoked");
+    }
+    if (store().data.oauth.password_fingerprint !== fingerprint) store().update((d) => void (d.oauth.password_fingerprint = fingerprint));
+  }
+  if (opts.remote) rememberPasswordFingerprint();
+
+  let watcherStarted = false;
+  function startWatcherOnce(): void {
+    if (watcherStarted || !isConfigured()) return;
+    watcherStarted = true;
+    startWatcher();
+  }
+
+  function notify(text: string): void {
+    if (!config.notifyWebhookUrl) return;
+    const slack = /hooks\.slack\.com/.test(config.notifyWebhookUrl);
+    fetch(config.notifyWebhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(slack ? { text } : { source: config.appName, type: "sign_in", text }),
+    }).catch((err) => log("notify failed", (err as Error).message));
+  }
+
+  // --- Status page, health, legal ---
+
+  const callbackUrl = new URL("/callback", baseUrl).href;
+  // The setup page reads the chosen key file in the browser, which needs one inline script.
+  const setupCsp = "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'";
+
+  app.get("/", (_req, res) => {
+    if (setupAvailable()) return void res.set("Content-Security-Policy", setupCsp).type("html").send(setupPage({ baseUrl: config.baseUrl }));
+    res.type("html").send(statusPage({ problems: setupProblems(), mcpUrl: mcpUrl.href, callbackUrl }));
+  });
+
+  app.post("/setup", express.urlencoded({ extended: false, limit: "64kb" }), (req, res) => {
+    if (!setupAvailable()) return void res.status(404).type("html").send(failedPage("Setup is already complete."));
+    const body = req.body as Record<string, string | undefined>;
+    const error = applySetup(body);
+    if (error) return void res.status(400).set("Content-Security-Policy", setupCsp).type("html").send(setupPage({ error, values: { app_id: body.app_id, country: body.country }, baseUrl: config.baseUrl }));
+    log("setup completed via the setup page");
+    if (opts.remote) rememberPasswordFingerprint();
+    startWatcherOnce();
+    res.redirect(303, "/");
+  });
+
+  app.get("/healthz", (_req, res) => void res.json({ ok: true, version: VERSION, configured: isConfigured() }));
+
+  app.get("/privacy", (_req, res) => void res.type("html").send(privacyPage()));
+  app.get("/terms", (_req, res) => void res.type("html").send(termsPage()));
+
+  // --- OAuth server for the MCP connector (single user) ---
+
+  if (opts.remote) app.use(
+    mcpAuthRouter({
+      provider,
+      issuerUrl: baseUrl,
+      resourceServerUrl: mcpUrl,
+      resourceName: "bank-mcp",
+      scopesSupported: ["bank:read"],
+      clientRegistrationOptions: { clientSecretExpirySeconds: 0 },
+    }),
+  );
+
+  if (opts.remote) app.post("/login", express.urlencoded({ extended: false }), (req, res) => {
+    const { request, password } = req.body as Record<string, string | undefined>;
+    const result = provider.completeLogin(String(request ?? ""), String(password ?? ""), req.ip ?? "unknown");
+    if ("redirect" in result) return void res.redirect(302, result.redirect);
+    if (result.requestId) return void res.status(401).type("html").send(loginPage({ requestId: result.requestId, error: result.error }));
+    res.status(400).type("html").send(signInFailedPage(result.error));
+  });
+
+  // --- MCP endpoint (stateless: one transport per request) ---
+
+  const bearer = requireBearerAuth({ verifier: provider, resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl) });
+
+  if (opts.remote) app.post("/mcp", bearer, express.json({ limit: "1mb" }), async (req, res) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      log("mcp request failed", err);
+      if (!res.headersSent) res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
+    }
+  });
+
+  if (opts.remote) app.get("/mcp", bearer, (_req, res) => void res.status(405).set("Allow", "POST").json({ error: "This server is stateless; use POST." }));
+  if (opts.remote) app.delete("/mcp", bearer, (_req, res) => void res.status(405).set("Allow", "POST").json({ error: "This server is stateless; use POST." }));
+
+  // --- Enable Banking redirect target ---
+
+  app.get("/callback", async (req, res) => {
+    const { code, state, error, error_description } = req.query as Record<string, string | undefined>;
+    const pending = state ? store().takePendingAuth(state) : undefined;
+    const failed = (msg: string) => res.status(400).type("html").send(failedPage(msg));
+
+    if (error || !code) return void failed(error_description || error || "The bank did not return an authorization code.");
+    if (!pending) return void failed("Unknown or expired authorization. Start again from your assistant.");
+
+    try {
+      const session = await eb.createSession(code);
+      store().addSession(session);
+      log(`bank connected: ${session.aspsp.name}, ${session.accounts.length} account(s)`);
+      res.type("html").send(connectedPage(session));
+    } catch (err) {
+      const msg = err instanceof EnableBankingError ? `Enable Banking returned ${err.status}: ${err.body.slice(0, 300)}` : (err as Error).message;
+      log("callback failed", msg);
+      failed(msg);
+    }
+  });
+
+  return Object.assign(app, { startWatcherOnce });
+}