docs(design): propose a separate MCP broker service for mecak8s

[jhrozek]

Summary

• Adds a design proposal, docs/design/mcp-broker-service.md, for moving the MCP broker (ToolHive plus mecatl's session wrapper) out of mecak8s agent pods into a separate singleton mecabroker service.
• Why: today every connected user's upstream OAuth tokens are reachable from the agent process and from the session-store Redis every agent pod can read, and broker state forces the whole mecak8s deployment to one replica with a Recreate rollout.
• The doc covers who authenticates to whom, the four bindings that connect a tool call to its state (deployment, session, call, user), restarts with encrypted retained tokens, owners and grant holders, what the change protects against, alternatives, and costs. A separate section covers future iterations: per-call user checks through RFC 8693 delegated tokens, grants for schedules and long runs, broker-side user login, agent-definition identity, external vMCP, and a shell in mecak8s.
• Indexed from docs/design/README.md.

Development stage

• Plan / Interface
• Implementation
• Combined
• Spike / Routine / Cleanup — acceptance-plan spine exempt

Contract linkage

• Work classification: Routine
• Classification rationale: documentation-only design proposal; no code, interface, or behavior change. The implementation is Architectural and will get its own acceptance plan and ADR after this design is reviewed.
• Decision record: None — this records a proposal for discussion; decisions will be recorded as ADRs with the acceptance plan.
• Human waiver of spine: No
• Acceptance plan: N/A (follows this design)
• Human decisions resolved and recorded: N/A — design review is the purpose of this PR
• Plan / Interface PR: N/A
• Approved commit baseline: N/A
• Combined/exemption rationale: Routine docs change.

Interface conformance

• None; no interface change.

Issue relationship

None.

Type of change

• Documentation/process

Test plan

Baseline checks

• Markdown changed: doc link checks (matlatl check . --strict: 0 broken links, 0 orphans) and go test ./docs/lint/ (citation and ADR checks) pass.

Runtime gates (task lint, task test, demo) are not applicable to a docs-only change.

User-facing change

None.

Special notes for reviewers

• This describes the target design, not the current state of the implementation branch. Parts of it already exist on that branch; some existing code will need reshaping to match (for example, retained-token custody keyed to the grant holder with the guard held in the broker).
• The security claim is deliberately narrow for the first release: no upstream token or client secret is ever in an agent pod, but a compromised agent pod can still use broker tools for any session. Narrowing that to active users is the first future iteration.
• Open items called out in the doc: an approval step for schedule grants that a compromised pod can't fake, and keeping retained tokens alive after the session that created a schedule is gone.

[jhrozek]

This was superseded by PR #2121