Milestone 3.5.E.4 — MCP Observability and Rate Limiting

Status: Planned
Goal: Track E — MCP Tool Surface
Phase: 3.5 — Extraction & Context Assembly
Estimated effort: 1 day
Track: Track E — MCP Tool Surface
Depends on: Milestone 3.5.E.3 (record_feedback tool)

Why This Milestone Exists

An MCP server exposed to external agent frameworks is a new, untrusted-by-default entry point — it needs the same operational rigor as the HTTP proxy.

Requirements

Every tool call traced to ClickHouse mcp_tool_calls table (org_id, agent_id, tool_name, latency_ms, success, error_code) — table created in 2.5.G6.M1 / ADR-0050; this milestone must not CREATE TABLE again
Rate limiting reuses packages/ratelimit's Limiter interface, keyed ratelimit:{org_id}:mcp:{unix_minute} — independent budget from chat-completions
Circuit breaker: AuthService gRPC unreachable → MCP server fails closed (fail-closed already shipped in G6; this milestone adds breaker polish)

Orientation (indicative)

Named paths, package layouts, libraries, schemas, env vars, and commands anywhere on this page are rough sketches for orientation — inspiration and a baseline, not a required change list.

During implementation, expect to:

open the live tree and follow existing patterns before inventing new ones
research current constraints (latency, tenancy, deploy shape, libraries) more deeply than this page can
advance the design beyond the sketch where measurement or code reality says so
land work in different filenames, merged packages, deferred docs, or new surfaces when the situation calls for it

Prefer outcomes over matching any particular file tree or command sequence.

Areas that may be involved (situational — not a checklist):

MCP server surface
Memory service / repositories

Success signals

Outcome-oriented signals that the milestone is in good shape. Exact filenames, package layouts, and commands may differ from any sketches above.

mcp_tool_calls ClickHouse table + migration, TTL matching llm_traces (90 days)
Rate limit integration test: burst of search_memory calls correctly 429s at threshold, independent of proxy chat rate limit
Fault injection test: AuthService down → MCP calls fail closed within timeout, no hang
Repo guards / CI checks still pass

Prerequisites

Milestone 3.5.E.3 (record_feedback tool)