# Audit Agentic Mcp

> Use if auditing or designing an MCP server for agent-readiness — framework, security, context.

- **Type:** Skill
- **Install:** `agentstack add skill-yigitkonur-skills-by-yigitkonur-audit-agentic-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yigitkonur](https://agentstack.voostack.com/s/yigitkonur)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yigitkonur](https://github.com/yigitkonur)
- **Source:** https://github.com/yigitkonur/skills-by-yigitkonur/tree/main/plugins/audit-agentic-mcp/skills/audit-agentic-mcp

## Install

```sh
agentstack add skill-yigitkonur-skills-by-yigitkonur-audit-agentic-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 → route to `build-mcp-server-sdk-v1`
- Writing or fixing raw `@modelcontextprotocol/server` v2 alpha code → route to `build-mcp-server-sdk-v2`
- 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`
- Enforcing TypeScript Clean Architecture layering on `mcp-use/server` → route to `build-clean-mcp-architecture`
- CLI agent-readiness (not MCP) → route to `audit-agentic-cli`
- Migrating SDK v1 code to v2 → route to `convert-mcp-sdk-v1-to-v2`

## Hard rules (load-bearing)

| # | 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` |

## 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
   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:
   ```bash
   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.

| 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` |

## Companion skills (route fixes here)

| Skill | When to pick | Tradeoff |
|---|---|---|
| [`build-mcp-server-sdk-v1`](../../../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`](../../../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`](../../../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`](../../../convert-mcp-sdk-v1-to-v2/) | Migrating existing SDK v1 code to v2 alpha | Targets the migration only |
| [`test-by-mcpc-cli`](../../../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`](../../../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`](../../../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 |

## 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

| 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` |

## Common pitfalls

| # | 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` |

## Reference routing table

### Pattern files (`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

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yigitkonur](https://github.com/yigitkonur)
- **Source:** [yigitkonur/skills-by-yigitkonur](https://github.com/yigitkonur/skills-by-yigitkonur)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yigitkonur-skills-by-yigitkonur-audit-agentic-mcp
- Seller: https://agentstack.voostack.com/s/yigitkonur
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.