audit-agentic-mcp — Audit, Optimize, Architect MCP Servers

The agent-readiness front door for MCP servers. Decides what is wrong, what should change, which reference applies, which companion skill implements the fix, and how to verify the result.

This skill does not write SDK code. It diagnoses, prescribes, and routes.

When to use

Trigger when the user asks any of:

• "audit my MCP server" / "review this MCP server" / "is my MCP server agent-ready?"
• "optimize my MCP server" / "my agent keeps misusing this tool — what's wrong?"
• "design a new MCP server" / "should this be an MCP or a CLI?"
• "score this MCP server's tool design / schemas / auth / context budget"
• "my MCP server returns too much context" / "my agent picks the wrong tool"
• "harden my MCP server" / "production-readiness check for MCP"
• "which MCP framework should I pick — SDK v1, SDK v2, or mcp-use?"

Do NOT use this skill for:

• Writing or fixing raw @modelcontextprotocol/sdk v1 code → out of scope; follow the SDK's own docs
• Writing or fixing raw @modelcontextprotocol/server v2 alpha code → out of scope; follow the SDK's own docs
• Writing or fixing mcp-use/server code → route to build-mcp-use-server
• Live CLI smoke-testing of an MCP server → route to test-by-mcpc-cli
• CLI agent-readiness (not MCP) → route to audit-agentic-cli
• Migrating SDK v1 code to v2 → out of scope; follow the SDK's own migration guide

Hard rules (load-bearing)

Two modes

Mode A — Audit / optimize an existing MCP server

Pick this when MCP-shaped code already exists.

1. Explore. Start with the helper scripts:

   bash skills/audit-agentic-mcp/skills/audit-agentic-mcp/scripts/audit-mcp-server.sh .
   bash skills/audit-agentic-mcp/skills/audit-agentic-mcp/scripts/measure-context-budget.sh .

   Then confirm with direct searches:

   tree . -I node_modules --dirsfirst -L 3
   rg -n -l "McpServer|FastMCP|server\.tool|@tool|@mcp\.tool|registerTool|Server\(" . -g '!node_modules'
   rg -n "server\.tool|@tool|registerTool|def .*tool|tool\(" . -g '!node_modules'
   rg -n -l "z\.|inputSchema|BaseModel|Field\(|pydantic|jsonschema" . -g '!node_modules'
   rg -n "stdio|streamable|sse|transport" . -g '!node_modules'

   See scripts/audit-mcp-server.sh.md and scripts/measure-context-budget.sh.md for what the helpers cover and what to read next.

   If tree is missing, find . -maxdepth 3 -type d. If rg is missing, grep -R. If no MCP-shaped code exists after checking root and likely server dirs (src/, server/, servers/, app/, apps/, packages/, services/, mcp/), report the missing prerequisite and switch to Mode B only if the user actually wants a new server.

2. Detect framework, then route mechanics. Read manifest, entry point, tool registration, schemas, transport/auth config. Keep this skill on audit reasoning; route implementation mechanics to the companion table below.
3. Score and prioritize. Produce the audit Output Contract below. Tie every finding to real evidence or a labeled assumption. Thresholds in references are diagnostic cues, not verdicts.
4. Apply only in implementation scope. For optimize/fix, edit the in-scope findings and verify with one live route. For audit/review, stop at the report.

Audit Output Contract

• target path and detected framework
• short scorecard across: tool interface, schemas/responses, errors, security/auth, context/cost, client compatibility, ops/testing, and architecture
• prioritized findings — each with severity, evidence path/line, impact, recommended fix, companion-skill route
• verification plan: test-by-mcpc-cli, MCP Inspector, unit/integration, or targeted manual check
• assumptions and items not touched

Mode B — Architect a new MCP server

Pick this when no MCP-shaped code exists yet, or the user wants a fresh server alongside an existing one.

1. Run the interview in references/decision-trees/brainstorming-new-mcp.md.
2. Choose framework and companion via references/decision-trees/companion-toolchain.md.
3. Cross-check the sketch with references/decision-trees/design-phase.md for schema portability and architecture gotchas.
4. If MCP is the wrong primitive, route to references/patterns/mcp-vs-cli.md and recommend CLI, agent skill, or a smaller script instead.
5. Hand off to the chosen companion only after the architecture sketch is signed off.

Architect Output Contract

• chosen framework and companion skill
• why MCP is better than CLI, agent skill, or a smaller primitive — sourced from references/patterns/mcp-vs-cli.md
• security posture, context-budget posture, and production-readiness risks
• validation plan before and after implementation

Minimal read sets

Do not load the whole reference tree by default. Start with the smallest bundle.

Companion skills (route fixes here)

Raw official-SDK work (@modelcontextprotocol/sdk v1, @modelcontextprotocol/server v2 alpha) and v1 → v2 migration have no companion skill in this pack. Use the SDK's own docs: v1 is the production default with the widest client compatibility; v2 is for greenfield projects that accept alpha risk after checking npm and the docs (Node 20+, ESM, Zod v4, no server-side OAuth).

Execution rhythm

• Audit/review request → produce the full audit report and stop. No code edits.
• Optimize/fix request with clear scope → state assumptions and tradeoffs upfront, apply in-scope edits, verify.
• Ask only when the target server is ambiguous, multiple servers are in scope and the user did not request a repo-wide audit, or the next action is destructive or externally visible.
• After every applied optimization, pick one live verification route: test-by-mcpc-cli, MCP Inspector, unit/integration test, or targeted manual endpoint check.

Decision tree — what aspect needs attention?

What aspect of the MCP server is in scope?
│
├── Brand new server, no code yet
│   ├── references/decision-trees/brainstorming-new-mcp.md
│   └── references/decision-trees/companion-toolchain.md
│
├── Architecture decision — should this even be an MCP server?
│   └── references/patterns/mcp-vs-cli.md
│
├── Tool interface quality
│   ├── REST-wrapper tools ───────────── references/patterns/tool-design.md
│   ├── Wrong tool selected ──────────── references/patterns/tool-descriptions.md
│   └── Weak next-action guidance ────── references/patterns/tool-responses.md
│
├── Input / output reliability
│   ├── Schema parse failures ────────── references/patterns/schema-design.md
│   ├── Poor recovery errors ─────────── references/patterns/error-handling.md
│   ├── Response format choice ───────── references/decision-trees/response-format.md
│   └── Error strategy choice ────────── references/decision-trees/error-strategy.md
│
├── Security and identity
│   ├── Security posture flow ────────── references/decision-trees/security-posture.md
│   ├── Generic defenses ─────────────── references/patterns/security.md
│   ├── OAuth / CIMD / OBO ───────────── references/patterns/auth-identity.md
│   └── Named attacks / CVEs ─────────── references/patterns/threat-catalog.md
│
├── Context, tokens, and cost
│   ├── Context budget ───────────────── references/patterns/context-engineering.md
│   ├── Prompt-caching economics ─────── references/patterns/caching-economics.md
│   ├── Tool count cliffs ────────────── references/decision-trees/tool-count.md
│   └── Progressive loading ──────────── references/patterns/progressive-discovery.md
│
├── Protocol depth
│   ├── Sampling / elicitation / roots ─ references/patterns/advanced-protocol.md
│   ├── Resources + prompts ──────────── references/patterns/resources-and-prompts.md
│   └── Tool response authority ──────── references/patterns/prompt-gates.md
│
├── Client + model compatibility
│   ├── Per-client quirks ────────────── references/patterns/client-compatibility.md
│   └── Per-model behavior ───────────── references/patterns/model-behavior.md
│
├── Architecture & scaling
│   ├── Agentic workflows ────────────── references/patterns/agentic-patterns.md
│   ├── Multi-server composition ─────── references/patterns/composition.md
│   ├── Growth / load distribution ───── references/decision-trees/scaling.md
│   └── Early design decisions ───────── references/decision-trees/design-phase.md
│
├── Operations, testing, deployment
│   ├── Transport + ops ──────────────── references/patterns/transport-and-ops.md
│   ├── Hosting platforms ────────────── references/patterns/deployment-platforms.md
│   ├── Session lifecycle ────────────── references/patterns/session-and-state.md
│   ├── Testing strategy ─────────────── references/patterns/testing.md
│   └── Production readiness ─────────── references/decision-trees/production-readiness.md
│
└── Distribution and trust
    ├── Vendor exemplars ─────────────── references/patterns/exemplar-servers.md
    └── Registries / gateways ───────── references/patterns/registry-and-distribution.md

Quick reference card

Common pitfalls

Reference routing table

Pattern files (references/patterns/)

Decision-tree files (references/decision-trees/)

Freshness checks

Before making version-sensitive claims, verify current MCP SDK, mcp-use, client compatibility, pricing, CVEs, and registry status from primary sources. Start with npm package metadata and the official TypeScript SDK repository/release notes when framework guidance depends on SDK state.

Time-sensitive references — re-check before citing:

• references/patterns/auth-identity.md
• references/patterns/client-compatibility.md
• references/patterns/caching-economics.md
• references/patterns/deployment-platforms.md
• references/patterns/model-behavior.md
• references/patterns/registry-and-distribution.md
• references/patterns/threat-catalog.md

Delegation policy

Use subagents only when the runtime supports them and project policy allows it. Delegate independent current-research questions, broad codebase scans, or batch implementation after the user has authorized implementation scope. Pass outcome, constraints, and binary done criteria. Do not delegate work that is faster as a local read-plus-edit.