Menu
Use if auditing or designing an MCP server for agent-readiness โ framework, security, context.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use skill if you are exhaustively testing or release-gating martool CLI commands in a source checkout or deployed Coolify container over SSH, without local Docker or provider spend.
Use if driving agent-browser for Chrome/CDP automation, @ref snapshots, tabs, or verification.
Use if testing or debugging an iOS app via agent-device CLI โ simulator flows, evidence, bug triage.
Use if supervising Jean agents through MCP and Computer Use for monitoring, recovery, or closure.
Use if auditing or designing a CLI for agent/LLM use โ JSON output, exit codes, non-interactive.
Use if verifying claimed-done work or auditing session/plan/branch completion with evidence.
| name | audit-agentic-mcp |
| description | Use if auditing or designing an MCP server for agent-readiness โ framework, security, context. |
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.
Trigger when the user asks any of:
mcp-use?"Do NOT use this skill for:
@modelcontextprotocol/sdk v1 code โ route to build-mcp-server-sdk-v1@modelcontextprotocol/server v2 alpha code โ route to build-mcp-server-sdk-v2mcp-use/server code โ route to build-mcp-use-servertest-by-mcpc-climcp-use/server โ route to build-clean-mcp-architectureaudit-agentic-cliconvert-mcp-sdk-v1-to-v2| # | Rule | Reference |
|---|---|---|
| 1 | Explore the codebase before asking. Run helper scripts and rg first. | scripts/audit-mcp-server.sh.md |
| 2 | Audit requests stop at the report. Optimize/fix requests apply edits and verify. | โ |
| 3 | Every finding cites file path and line, real code or labeled assumption. | โ |
| 4 | One server at a time. If multiple servers exist, inventory and ask which is in scope. | โ |
| 5 | Map tools to user intent โ never wrap REST endpoints one-to-one. | references/patterns/tool-design.md |
| 6 | Flatten schemas past one nesting level; keep 3โ6 required params. | references/patterns/schema-design.md |
| 7 | Curate tool responses for LLM consumption โ never return raw upstream JSON. | references/patterns/tool-responses.md |
| 8 | Use isError in result content for tool failures. Reserve protocol errors for transport. | references/patterns/error-handling.md |
| 9 | Validate all LLM input server-side; never trust generated input. | references/patterns/security.md |
| 10 | Use Streamable HTTP for new remote deployments โ not SSE. | references/patterns/transport-and-ops.md |
| 11 | Use progressive discovery past ~20 tools, not eager registration. | references/patterns/progressive-discovery.md |
| 12 | Tool descriptions are prompt engineering โ treat them with care. | references/patterns/tool-descriptions.md |
| 13 | Capability-gate sampling, elicitation, and roots โ never silently drop. | references/patterns/advanced-protocol.md |
| 14 | Use OBO with audience checks; never forward user tokens to upstream APIs. | references/patterns/auth-identity.md |
| 15 | Verify after every applied edit. Pick one live route. | references/patterns/testing.md + test-by-mcpc-cli |
Pick this when MCP-shaped code already exists.
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.
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.
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.
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.
test-by-mcpc-cli, MCP Inspector, unit/integration, or targeted manual checkPick this when no MCP-shaped code exists yet, or the user wants a fresh server alongside an existing one.
references/decision-trees/brainstorming-new-mcp.md.references/decision-trees/companion-toolchain.md.references/decision-trees/design-phase.md for schema portability and architecture gotchas.references/patterns/mcp-vs-cli.md and recommend CLI, agent skill, or a smaller script instead.references/patterns/mcp-vs-cli.mdDo not load the whole reference tree by default. Start with the smallest bundle.
| Work | Read first |
|---|---|
| Existing-server quick audit | scripts/audit-mcp-server.sh.md, scripts/measure-context-budget.sh.md, references/patterns/tool-design.md, references/patterns/schema-design.md, references/patterns/tool-responses.md, references/patterns/error-handling.md, references/patterns/testing.md |
| Security / auth audit | references/decision-trees/security-posture.md, references/patterns/security.md, references/patterns/auth-identity.md, references/patterns/threat-catalog.md |
| Context / cost audit | scripts/measure-context-budget.sh.md, references/patterns/context-engineering.md, references/patterns/caching-economics.md, references/decision-trees/tool-count.md, references/patterns/progressive-discovery.md |
| New-server architecture | references/decision-trees/brainstorming-new-mcp.md, references/decision-trees/companion-toolchain.md, references/decision-trees/design-phase.md, references/patterns/mcp-vs-cli.md |
| Skill | When to pick | Tradeoff |
|---|---|---|
build-mcp-server-sdk-v1 | Production-default raw SDK with widest client compatibility, stdio or HTTP | Manual transport/OAuth wiring; deprecated overloads still compile |
build-mcp-server-sdk-v2 | New greenfield projects accepting v2 alpha risk after checking npm and docs | Alpha APIs can change; Node 20+/ESM/Zod v4; no server-side OAuth |
build-mcp-use-server | New HTTP-first TypeScript server wanting mcp-use/server conventions, widgets/apps, OAuth helpers | Locks into mcp-use/server imports; less bare-metal control |
convert-mcp-sdk-v1-to-v2 | Migrating existing SDK v1 code to v2 alpha | Targets the migration only |
test-by-mcpc-cli | Repeatable stdio/Streamable HTTP smoke checks, JSON scripting, post-edit verification | Requires mcpc 0.2.x locally |
build-clean-mcp-architecture | TypeScript mcp-use/server audit hits layer-boundary, folder-layout, or dependency-direction issues | Layer discipline; not a replacement for this agent-readiness audit |
audit-agentic-cli | The interface should stay CLI-first or the task is CLI agent-readiness, not MCP | CLI contract work, not MCP protocol work |
test-by-mcpc-cli, MCP Inspector, unit/integration test, or targeted manual endpoint check.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
| You want to... | Start here |
|---|---|
| Architect a brand-new MCP | references/decision-trees/brainstorming-new-mcp.md โ references/decision-trees/companion-toolchain.md |
| Decide MCP vs CLI vs agent skill | references/patterns/mcp-vs-cli.md |
| Evaluate tool interface quality | references/patterns/tool-design.md โ references/patterns/tool-descriptions.md |
| Fix schema parse failures | references/patterns/schema-design.md โ references/decision-trees/design-phase.md |
| Improve error recovery | references/decision-trees/error-strategy.md โ references/patterns/error-handling.md |
| Harden security posture | references/decision-trees/security-posture.md โ references/patterns/security.md โ references/patterns/auth-identity.md |
| Reduce context / token usage | scripts/measure-context-budget.sh.md โ references/patterns/context-engineering.md |
| Manage 20+ tools | references/decision-trees/tool-count.md โ references/patterns/progressive-discovery.md |
| Add sampling, elicitation, or roots | references/patterns/advanced-protocol.md |
| Pick deployment platform | references/patterns/deployment-platforms.md |
| Design for a specific client | references/patterns/client-compatibility.md |
| Publish to a registry | references/patterns/registry-and-distribution.md |
| Validate with live tests | references/patterns/testing.md โ test-by-mcpc-cli |
| # | Pitfall | Fix |
|---|---|---|
| 1 | Wrapping every REST endpoint as a tool | Design around user intent โ references/patterns/tool-design.md |
| 2 | Deeply nested JSON schemas | Flatten to one level, 3โ6 params โ references/patterns/schema-design.md |
| 3 | Returning raw API JSON | Curate and summarize โ references/patterns/tool-responses.md |
| 4 | Throwing protocol errors for tool failures | Use isError in result content โ references/patterns/error-handling.md |
| 5 | No input validation | Validate server-side โ references/patterns/security.md |
| 6 | Registering 20+ tools eagerly | Progressive discovery โ references/patterns/progressive-discovery.md |
| 7 | Vague tool descriptions | Treat descriptions as prompt engineering โ references/patterns/tool-descriptions.md |
| 8 | No live verification after edits | Use test-by-mcpc-cli, Inspector, unit tests, or endpoint checks |
| 9 | Using SSE for new remote deployments | Streamable HTTP only โ references/patterns/transport-and-ops.md |
| 10 | Ignoring session cleanup | Lifecycle management โ references/patterns/session-and-state.md |
references/patterns/)| File | Read when... |
|---|---|
tool-design.md | Evaluating tool granularity, intent-based design, naming |
tool-descriptions.md | Diagnosing tool selection, improving description quality |
tool-responses.md | Optimizing return shape, picking output format, reducing tokens |
schema-design.md | Fixing parse failures, flattening schemas, trimming required params |
error-handling.md | Improving recovery, retry loops, circuit breakers |
security.md | Generic defenses: injection vectors, sandboxing, auth basics |
threat-catalog.md | Named MCP attacks, dated CVEs, defense tooling, audit checklist |
auth-identity.md | OAuth profile, RFC 9728 PRM, CIMD, OBO, step-up consent |
context-engineering.md | Token-budget diagnosis, context window optimization, tiered verbosity |
caching-economics.md | Provider-side prompt caching, write premiums, TTL, cost math |
progressive-discovery.md | Managing 20+ tools, dynamic tool loading |
agentic-patterns.md | Agent loops, multi-step workflows, ordering constraints |
composition.md | Multi-server setups, gateway federation, meta-server patterns |
prompt-gates.md | Tool response authority, approval workflows, guardrails |
resources-and-prompts.md | Resource and prompt primitive usage, data-exposure strategy |
session-and-state.md | Session lifecycle, state leaks, cleanup, application-level caching |
testing.md | Eval-driven development, regression testing, CI integration |
transport-and-ops.md | Transport choice, deployment config, monitoring, connection management |
deployment-platforms.md | Hosting platforms and deployment constraints |
mcp-vs-cli.md | Deciding whether MCP is the right primitive vs CLI, bash, skills, or hybrid |
client-compatibility.md | Per-client truth table, silent drops, partial support, workarounds |
model-behavior.md | Per-model tool-use benchmarks, idioms, pricing |
advanced-protocol.md | Sampling, elicitation, roots, completions, progress, cancellation, _meta |
exemplar-servers.md | Comparing design against production vendor servers |
registry-and-distribution.md | Official Registry, Smithery, Docker MCP Catalog, gateways, trust signals |
references/decision-trees/)| File | Read when... |
|---|---|
brainstorming-new-mcp.md | Mode B interview, framework picker, architecture sketch |
companion-toolchain.md | Choosing build, test, architecture, CLI, or no-MCP companion route |
design-phase.md | Early architecture decisions, cross-model schema portability |
tool-count.md | How many tools to expose; organizing a large surface |
response-format.md | Text vs structured content vs mixed |
error-strategy.md | Fail-fast vs retry vs fallback |
security-posture.md | Threat model selection, full security audit flow |
scaling.md | Growth, multi-server setups, load distribution |
production-readiness.md | Pre-deploy checklist, operational readiness |
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.mdreferences/patterns/client-compatibility.mdreferences/patterns/caching-economics.mdreferences/patterns/deployment-platforms.mdreferences/patterns/model-behavior.mdreferences/patterns/registry-and-distribution.mdreferences/patterns/threat-catalog.mdUse 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.