使用说明
mcp-audit — MCP Configuration Audit Prototype
A Claude Code plugin experiment for inspecting MCP configuration shape, tool-count pressure, duplicate names, stale servers, and other operational signals that can make tool-heavy agent environments harder to reason about.
Maturity: public diagnostic prototype. This repo is useful as evidence of MCP operational debugging work, but it is not a current compatibility guarantee for Claude Code and it does not claim that every heuristic here still maps to the latest Claude Code runtime behavior.
Claude Code, MCP clients, caching behavior, transport lifecycles, and pricing can change. Any runtime-specific hypothesis in this repository should be reproduced against the current version before it is treated as a production finding.
Why this exists
Tool-heavy agent setups create a practical class of problems that are easy to miss when each MCP server is evaluated independently:
- duplicate or colliding tool names;
- unexpectedly large aggregate tool surfaces;
- stale/disconnected server entries;
- configuration drift between projects;
- tool-schema/order instability that can change request shape;
- transports that are loaded even when the project does not need them.
The plugin was built to make those conditions visible from the developer environment instead of discovering them only after latency, context, or reliability degrades.
What the public prototype contains
The repository includes Claude Code plugin assets under:
.claude-plugin/
agents/
commands/
hooks/
skills/
The audit workflow is oriented around configuration inspection and operator recommendations rather than a standalone runtime service.
Heuristics represented in the prototype
| Signal | Why it matters |
|---|---|
| Duplicate tool names | Ambiguous/colliding interfaces are difficult to reason about and may be handled differently across clients |
| High per-server tool count | Larger tool surfaces consume context and increase selection complexity |
| High aggregate tool count | Multiple individually reasonable servers can create an unexpectedly large combined interface |
| Stale/disconnected servers | Dead configuration creates failed calls and operational noise |
| Tool/schema ordering changes | Request-shape drift can matter for caching, reproducibility, and debugging |
| Broad project-wide MCP loading | Loading every integration everywhere increases blast radius and cognitive overhead |
Thresholds and impact estimates should be treated as diagnostic heuristics, not universal limits.
Usage
If installed as a Claude Code plugin, the repository defines audit/fix-oriented commands and supporting agent/skill assets. Inspect the files in commands/, agents/, hooks/, and skills/ before enabling them in an environment you care about.
Because Claude Code's plugin/runtime interfaces evolve, this repository intentionally does not promise a current one-line installation command or claim compatibility with every present release.
Historical investigation boundary
An earlier version of this README presented a specific tool-ordering/cache hypothesis and fixed cost multipliers as if they were durable facts about Claude Code.
That was too strong.
The durable engineering lesson is narrower:
When a large dynamic tool surface becomes part of an LLM request, changes in tool identity, schema, ordering, or scope can affect request size, reproducibility, caching behavior, and runtime reliability. Measure the actual client/version before assigning cost or performance impact.
This repo preserves the diagnostic approach without presenting version-sensitive observations as timeless platform behavior.
Where this fits in the portfolio
This is a supporting repository, not the primary Forward Deployed Engineering proof surface.
For stronger runnable/public evidence, start with:
License
MIT
