Design: mcpx upstream question rate limits — one limiter at the client choke point, keyed by the configured server #2333

Design — filed by repo-design-architect-code pass 14, 2026-10-29. Origin: #2192 (split of #1957, ex-nix#257). Design doc: files/designs/code-mcpx-upstream-question-rate-limits.md in the keep-the-four-repos-healthy goal workspace. No user/review: #2192's acceptance is explicit and the judgment calls below are the architect's recorded decisions.

Problem

An upstream MCP server can ask mcpx's client questions — sampling (sampling/createMessage: a model call or a person's review) and elicitation (elicitation/create: a person's attention) — at any rate. A buggy upstream loops; a hostile one floods the broker with questions, each holding a TTL and a slot in every watching UI. The spec's security considerations say clients SHOULD implement rate limiting for both features; mcpx's conformance register records both as gaps (internal/conformance/coverage_clientfeatures.go:118-119): sampling has "no per-server or per-session limit", elicitation "no per-server limit" — the only bounds today are per-request (proto.askRounds = 8) and per-question TTL. #2192 names the work and its acceptance but leaves the mechanism open; this design records it and adopts #2192 as Phase 1 instead of filing a parallel.

Recorded decisions

1. One limiter, at Client.answer (internal/mcpclient/modern.go:288) — the single dispatch both eras reach (legacy via handleServerRequest, client.go:607; 2026 via resolveInput, modern.go:377). Enforced at entry, for sampling/createMessage and elicitation/create only, before the handler: an over-limit question never reaches the handler, the broker, or a person.
2. Keyed by the configured server, never the claimed one. Per-server bucket keyed by the pool's cfg.Name, pool-owned and passed via a new mcpclient.Options field; ServerInfo.Name is self-reported and is never a key. Per-session bucket is a field on Client (one Client = one session). Non-pool clients degenerate to per-session only — recorded, acceptable.
3. A question counts when admitted, once — whether later answered, declined or expired (the bounded resource is spent on the asking). Refusals count against neither bucket. Each 2026 inputRequests entry counts separately; askRounds still bounds rounds underneath.
4. Fixed per-minute windows, in memory, no new dependency (no limiter exists in-tree and x/time/rate is not in go.mod). Windows reset with the daemon; nothing persists.
5. Settings in the proto.* family (following proto.askRounds/proto.askTTL): proto.samplingPerMinute default 60 (per server), proto.samplingSessionPerMinute default 20, proto.elicitationPerMinute default 30; ScopeDaemon ints; 0 disables that bound.
6. Refusal is a named -32603 error, never a fabricated answer: rpcError -32603 with a message naming the limit, plus the refusal emitted via c.warn — following design mcpx: design — sampling trust boundary (reviewable, validated, honestly error-coded) #1834's "expiry stays -32603 named" precedent (the spec assigns no rate-limit code). For elicitation the refusal is the JSON-RPC error, NOT {action: "cancel"} — nobody declined; mcpx conformance: rate limits for sampling and elicitation requests (split of #1957) #2192 requires clear failure, not a silent drop.

Phases

• Phase 1 (ADOPTED — mcpx conformance: rate limits for sampling and elicitation requests (split of #1957) #2192): the limiter + the three settings + enforcement at answer per decisions 1–6, with mcpx conformance: rate limits for sampling and elicitation requests (split of #1957) #2192's named tests (burst refused, under-limit passes, per-server isolation) plus per-session isolation and the modern input_required path. mcpx conformance: rate limits for sampling and elicitation requests (split of #1957) #2192 already carries queue/queued with a triage packet in flight — triage records this phase structure instead of re-scoping or splitting it.
• Phase 2 (filed, gated on Phase 1): register truth-up — retire the two gap rows in coverage_clientfeatures.go, update the requirements.json client notes, verify the conformance-matrix rows, and post evidence on tracker mcpx: smaller conformance gaps -- user identity, annotation trust, rate limits, cursors, URI encoding, prompt validation, restart, invalidation #1957 closing its rate-limits cluster.

Alternatives rejected (detail in the design doc)

Broker-side enforcement (misses non-broker handlers and the modern in-client path); pool-side enforcement (server-initiated requests are only visible inside Client); token bucket (flood bound, not burst shaping; no new dependency); delay/queue instead of refuse (stale questions, invisible stalls, teaches a looping upstream nothing).

Explicitly out of scope

The server-side tasks-rate-limit gap (coverage_stateful.go:120, citing #209) — the other side of the protocol; it belongs to design #1554's operational-limits open question. Daemon-originated /v1/ask questions from local scripts — bounding those waits on the principals work (#1968/#1972).

Acceptance criteria

• A per-server rate limiter for upstream sampling/elicitation questions exists at the mcpx client choke point, keyed by the configured server, per the recorded decisions.
• The conformance register entries (internal/conformance/coverage_clientfeatures.go:118-119) are updated from gap to implemented with the limits named.
• mcpx conformance: rate limits for sampling and elicitation requests (split of #1957) #2192 (adopted as Phase 1 by this design) is updated with the implementation link, and its acceptance is checked off or carried into a follow-up issue.