tegwick d2ffd372b5 QONTO-WP-0003-T03: MCP client auth + shared multi-harness config snippet

Gate /mcp with a shared-secret bearer token (QONTO_ASSISTANT_MCP_TOKEN,
mcp_auth.py::BearerTokenAuthMiddleware, constant-time compare, REST
untouched) since no OIDC issuer exists in this fleet yet -- pointing
FastMCP's OAuth Protected Resource flow at a non-existent issuer would be
worse than not having it. This token is a service credential, never a bank
credential; per-actor identity stays the existing X-Actor-* convention.

Add docs/mcp-integration.md: tool catalog, the two-layer auth model (workload
auth today vs. deferred OIDC target), and one shared {"mcpServers": {...}}
client config snippet (url + headers) usable across Claude Code, Claude
Desktop, Cursor, and Codex/Grok-style harnesses.

Verified live using only that snippet: unauthenticated and wrong-token
requests get 401 before reaching any tool; a request built from the
snippet's URL + headers lists tools and calls qonto_org_summary
successfully against the fixture-backed server.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-23 09:41:25 +02:00

2.3 KiB

Raw Blame History

qonto-assistant

Policy-governed Qonto domain API and MCP assistant for Binky (and later multi-tenant dogfood).

One choke point for bank access across every coding agent and harness. Clients never hold the Qonto API key. v1 policy: read for awareness only — no spend, no volume-cost actions.

Start here

Doc	What
`INTENT.md`	Why this exists; boundaries
`specs/ArchitectureBlueprint.md`	Architecture, phases, policy model
`research/2026-07-21-mcp-gateway-and-governed-domain-assistant.md`	External + internal research
`docs/operator-runbook.md`	How to run and verify Phase 1

Status

Phase 1 runtime is implemented:

Python 3.12 service under src/qonto_assistant/
default-deny YAML policy
Qonto read-only client (organization, transactions)
REST endpoints: /v1/health, /v1/accounts, /v1/transactions, /v1/snapshot
audit metadata, rate limiting, concurrency bounds, tests

Phase 2 (MCP surface, workplans/QONTO-WP-0003-mcp-surface.md) is in progress: a streamable-HTTP MCP adapter is mounted at /mcp on the same capability core and policy kernel as REST, with tools qonto_org_summary, qonto_list_transactions, and qonto_cost_run_rate_hints. The endpoint is gated by a shared-secret bearer token (QONTO_ASSISTANT_MCP_TOKEN) — see docs/mcp-integration.md for the auth model, its gap vs. the OIDC/workload target, and the shared multi-harness client config snippet. The finance-qonto-read tool profile is not yet implemented.

Current verification:

PYTHONPATH=src ../state-hub/.venv/bin/python -m pytest → 16 passed
python3 -m compileall src tests scripts
../state-hub/.venv/bin/python scripts/smoke_rest_api.py --python ../state-hub/.venv/bin/python

Local fixture-backed smoke mode is available through QONTO_FIXTURE_DIR, so the service can be exercised without real Qonto credentials. The smoke path checks both a 31-day recent snapshot and a 90-day recurring-cost snapshot.

Normal local workflow, when toolchain support exists:

make install-dev
make test
make run

OpenBao lane: tenants/binky/qonto-api (ops-warden binky-qonto-api)
First pull / CostRunRate: binky-control BINKY-WP-0005

2.3 KiB Raw Blame History

qonto-assistant

Start here

Status

Related

2.3 KiB

Raw Blame History