Context-Efficient MCP Access Review

Traceability

• Spec ID: mcp-context-efficient-access-review
• Status: Implemented

Intent

Improve the MCP configuration review guidance so reviewers first establish whether a large effective MCP surface causes model-visible Schema, selection, round-trip, payload, or discovery pressure. Only then should the review propose Tool Search, MCP-to-CLI, Code Mode, or Context Engineering as targeted remediations without weakening authorization, audit, or evidence boundaries.

Acceptance Scenarios

• AC-1: The review keeps configured, effective, observed, healthy, and unavailable evidence separate from cleanup eligibility.
• AC-2: A high configured Server/tool count is a pressure signal, not by itself proof that remediation is required. The review distinguishes catalog size, effective/model-visible Schema, selection quality, tool-call round trips, polling, result payloads, and discovery turns.
• AC-3: After pressure is established, the review offers four targeted recommendations: Tool Search, MCP-to-CLI, Code Mode, and Context Engineering. It states the pressure each recommendation addresses and how they can layer.
• AC-4: Direct MCP remains the baseline or retained path when pressure is not established or native MCP semantics are needed. SaaS MCP is an important application scenario for the recommendations, not one of the four.
• AC-5: CLI and Code Mode recommendations preserve the underlying authentication, authorization, approval, secret-redaction, audit, timeout, retry, and output-boundary contracts.
• AC-6: The routed reference remains discoverable and the focused platform ordering and documentation-link tests pass.

Non-goals

• Implement an MCP gateway, tool-search runtime, CLI, Code Mode executor, or context graph.
• Classify every MCP installation as needing one of the four remediations.
• Change Qoder configuration precedence, cleanup classifications, or runtime mutation authority.
• Claim that measurements from one company, model, host, or workload are universal performance targets.

Plan and Tasks

1. Preserve the evidence ladder and cleanup classification contract in MCP Configuration Review.
2. Put context-pressure evidence before remediation and keep tool count separate from demonstrated model-context or workflow cost.
3. Add a compact four-recommendation table plus security and output invariants for Shell/CLI and Code Mode paths.
4. Tighten remediation and recommendation fields while keeping platform notes after the shared review contract.

Test and Review Evidence

• AC-1–AC-5: Review the rendered Markdown and local diff for decision clarity, scoped wording, and preserved evidence/authority boundaries.
• AC-6: Run npx vitest run test/skills-docs/coding-agent-platform-notes.test.mjs test/skills-docs/doc-link-graph.test.mjs.
• AC-6: Regenerate the routing graph with node scripts/doc-link-graph/cli.mjs skills/better-harness and rerun the doc-link test if the generated graph changes.
• AC-1–AC-6: Run git diff --check and validate the containing Skill with the Skill Creator quick validator.

Implementation evidence after the recommendation-trigger correction on 2026-08-31:

• node scripts/doc-link-graph/cli.mjs skills/better-harness regenerated the 39-file, 56-link graph without a tracked graph change.
• npx vitest run test/skills-docs/coding-agent-platform-notes.test.mjs test/skills-docs/doc-link-graph.test.mjs passed 12/12 tests across two files.
• python3 /Users/phodal/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/better-harness reported Skill is valid!.
• git diff --check passed for the tracked reference and generated graph; the new spec also passed an explicit trailing-whitespace check.

Risk is primarily premature remediation: a large catalog can be healthy when the host already loads tools lazily, while an apparently small catalog can still cause expensive polling or payloads. Review the final wording for an evidence trigger, targeted recommendation, success parity, bounded execution, and preserved host security boundaries.