Status: outline (draft). To be completed in Phase 1 (roadmap milestone 1.2). Based on a real pattern, with no client code or data.
Why MCP, and why wrap a legacy API
What the Model Context Protocol is, and why an MCP server is the socket between an agent and an API that was never designed for agents: you do not rewrite the API, you translate it into a contract an agent can consume without breaking it.
The pattern
- OpenAPI as the contract — version the spec locally.
- OAuth2 auth (ROPC / B2C) — credential handling and rotation.
- Degraded mode without credentials — the server boots and responds even when secrets are missing.
- Idempotency and safe retries on calls to the wrapped API.
- CLI smoke tests — fast end-to-end verification.
Design decisions and trade-offs
- Exposing fine-grained vs. coarse-grained tools.
- Which local documentation to expose to the agent, and how.
- Observability: structured logging of tool calls.
What I would do differently at scale
A gateway with centralized auth, secret management, and an eval harness for the agent’s responses. (Materialized in the “Agentic infra starter kit” showcase build.)