tegwick
d2ffd372b5
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>
59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# 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`](INTENT.md) | Why this exists; boundaries |
|
|
| [`specs/ArchitectureBlueprint.md`](specs/ArchitectureBlueprint.md) | Architecture, phases, policy model |
|
|
| [`research/2026-07-21-mcp-gateway-and-governed-domain-assistant.md`](research/2026-07-21-mcp-gateway-and-governed-domain-assistant.md) | External + internal research |
|
|
| [`docs/operator-runbook.md`](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:
|
|
|
|
```bash
|
|
make install-dev
|
|
make test
|
|
make run
|
|
```
|
|
|
|
## Related
|
|
|
|
- OpenBao lane: `tenants/binky/qonto-api` (ops-warden `binky-qonto-api`)
|
|
- First pull / CostRunRate: `binky-control` BINKY-WP-0005
|