binky-control/integrations/qonto-mcp.md

# Qonto MCP Integration — Design

> Status: design v1 — 2026-07-19 (BINKY-WP-0005, from AWQ-010).  
> Goal: the company Qonto account becomes an agent-readable finance source
> (balance, transactions, statements) through the sanctioned harness/MCP
> lane. **Read scopes first; payments/transfers are Red lane forever.**
> Credential provisioning is a single founder Red-lane step (DEC-2026-004).

## Variant decision (T01)

Two Qonto MCP options exist as of 2026-07:

| | Hosted connector | Self-hosted server |
| --- | --- | --- |
| Endpoint | `https://mcp.qonto.com/mcp` | `qonto/qonto-mcp-server` (GitHub), Docker image `qonto/qonto-mcp-server:latest` |
| Auth | OAuth (user identity, Business-API scopes) | `QONTO_API_KEY` + `QONTO_ORGANIZATION_ID` env vars (from Qonto `/settings/integrations`) |
| Transport | remote streamable-HTTP only | stdio (default) or `--transport streamable-http` |
| Tool surface | curated subset incl. **write** tools (cards, invoicing, requests); no transfers | organization info, accounts, transaction history, business operations |
| Custody fit | credentials live in the AI client's connector settings | env-name pattern — identical to email-connect |

**Chosen: self-hosted `qonto/qonto-mcp-server`.** The hosted connector is
exactly the "native integration" the corporate access policy forbids (OAuth
grant held by claude.ai/the client, outside OpenBao custody, write tools
bundled in). The self-hosted server consumes credentials only via env
*names*, runs inside the harness, and rides the existing warden delivery
path unchanged.

**Read-only enforcement:** Qonto API keys are not scope-limited server-side,
so read-only is enforced at **harness level**: tool allow-list restricted to
read tools (organization, accounts, transactions, statements, attachments,
labels). Card, invoicing, request and any future transfer tools are never
allow-listed. This mirrors the Green/Blue tool allow-list of
`scripts/rhythm-session.sh`. Any payment initiation stays founder-only in
the Qonto app — Red lane forever, not an automation target.

**Prerequisite check (founder, while in the dashboard — OH-2026-003):**
confirm the current Qonto plan exposes API keys under
`/settings/integrations`; note plan tier + monthly cost for
`finance/CostRunRate.md` row 4.

## Credential lane (T02) — ops-warden/OpenBao custody

Same pattern as `integrations/company-email-openbao.md`
(WARDEN-WP-0028 tenants custody):

| Item | Value |
| --- | --- |
| Mount | `tenants` |
| Path | `tenants/binky/qonto/api` |
| Fields | `QONTO_API_KEY`, `QONTO_ORGANIZATION_ID` |
| Policy | `workload-kv-read-binky-qonto-api` (to be created, warden playbook) |
| Catalog | `binky-qonto-api` (draft until provision) |
| Risk | high (full-scope bank API key — read-only is harness-enforced) |

```text
founder (Red lane, once)
   └─ bao kv put tenants/binky/qonto/api QONTO_API_KEY=@file QONTO_ORGANIZATION_ID=@file
        └─ OpenBao: tenants/binky/qonto/api
             └─ warden access binky-qonto-api --exec
                  └─ qonto-mcp-server (env names only) → harness read tools
                       └─ finance/CostRunRate.md + rhythm session feeds
```

### Founder provision (Red lane — interactive human shell)

```bash
# In the Qonto dashboard: /settings/integrations → create API key, note org ID
umask 077
# key into /tmp/qonto.key, org id into /tmp/qonto.org — private terminal only
bao kv put tenants/binky/qonto/api \
  QONTO_API_KEY=@/tmp/qonto.key \
  QONTO_ORGANIZATION_ID=@/tmp/qonto.org
shred -u /tmp/qonto.key /tmp/qonto.org
```

The organization ID is low-secrecy but lives with the key so consumers get
one fetch surface (same rule as IMAP username). **Key never in git/chat.**

## Consumer design (T03)

| Consumer | Use | Cadence |
| --- | --- | --- |
| Finance Steward rhythm session | balance snapshot + new-transaction triage → `finance/` metadata | weekly (harness-scheduled, after cutover) |
| `finance/CostRunRate.md` | resolve **TBC** rows: desk rent (HUB31 debit), Qonto plan fee; verify DATEV pass-through, railiance01 debit | first pull, then on statement events |
| OH-2026-003 package | real cost-vs-usage numbers; the working MCP is itself an argument FOR keeping Qonto | once, next office hour |
| Runway view (CostRunRate finding 2) | month-end balance series → liquidity awareness | monthly |

Rules:

- Transaction **metadata** (dates, counterparties, amounts) may land in
  `finance/` evidence tables; no bulk statement exports into git.
- Read-only tool allow-list per above; sessions run Green/Blue.
- **DUO boundary:** main accounting stays DATEV Unternehmen Online via the
  StB lane. Qonto MCP complements it (operational awareness, run-rate,
  runway); it does not replace Belegablage or bookkeeping.

## Execution checklist

1. [x] Variant + read-only enforcement decided (this doc)
2. [x] OpenBao lane designed (`tenants/binky/qonto/api`)
3. [x] DecisionQueue package prepared (DEC-2026-004)
4. [ ] **Red lane — founder:** approve DEC-2026-004; create API key; `bao kv put` via `@file`
5. [ ] Warden catalog `binky-qonto-api` draft → active after provision
6. [ ] First read-only pull; update CostRunRate TBC rows (BINKY-WP-0005-T05)
7. [ ] Wire Finance Steward recurring session (post-cutover, harness lane)

## See also

- `integrations/company-email-openbao.md` — custody pattern being mirrored
- `AutopilotWorkQueue.md` AWQ-010 (origin), `OfficeHourQueue.md` OH-2026-003
- Qonto docs: <https://docs.qonto.com/mcp/overview>,
  <https://github.com/qonto/qonto-mcp-server>