agentsclimarketplace
Sign in

Mcp server review

Skill selic/skills/skills/mcp-server-review

Review an MCP (Model Context Protocol) server for tool-design quality: tool naming and granularity, description/annotation accuracy, input schema strictness, output token budgets, error handling, and role/permission safety. Produces a prioritized findings list, not a rewrite. Use when reviewing, auditing, or hardening an MCP server or its tool definitions. Triggers on: review my MCP server, audit MCP tools, MCP tool design, are my tool descriptions good, MCP server quality.From its SKILL.md

Install
npx -y skills add selic/skills --skill mcp-server-review

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.8 KB, 768 tokens by cl100k_base, as published. Nobody here has run it

MCP server review

You audit an MCP server the way a demanding agent-integrator would: the tools are the API the model sees, so every name, description, and schema is a prompt. Find the highest-leverage defects and report them; do not silently rewrite the server.

Scope

Locate the tool surface first: Grep for tool registration (server.tool(, registerTool, @mcp.tool, tools/list handlers) and read the tool definitions + their handlers. Note the transport (stdio / streamable HTTP) and whether there is auth/RBAC.

Review dimensions

Go through each; for every issue capture file:line → problem → concrete fix.

1. Tool granularity & surface area

  • Too many near-duplicate tools (model can't choose) vs one overloaded tool with a mode grab-bag. Prefer a small set of sharp, task-shaped tools.
  • Missing the obvious workflow tool (e.g. a search that replaces 3 list calls).
  • Destructive and read tools not clearly separated.

2. Names

  • Verb-first, unambiguous, namespaced consistently (itglue_list_documents, not getDocs). A name should predict the effect without reading the description.

3. Descriptions & annotations

  • The description must state what it does, when to use it, and what it returns — it is read by the model, not a human changelog.
  • readOnlyHint / destructiveHint / idempotentHint must match reality. A destructive tool marked read-only is a safety bug.
  • Undocumented API quirks the model must know (required filters, replace-vs-merge semantics) belong in the description.

4. Input schema strictness

  • Every param typed and constrained (enums, min/max, formats) — loose string where an enum belongs makes the model guess.
  • Required vs optional correct; sensible defaults; pagination params present on list tools.
  • Reject invalid input with a clear message instead of forwarding garbage upstream.

5. Output shape & token budget

  • List tools must return summary fields, not full records, and must paginate — a single call must not blow the client's context window. Provide a get_* for the full record.
  • Return structured content where the SDK supports it, mirrored by readable text.
  • Large/binary payloads referenced, not inlined.

6. Error handling

  • Errors returned as tool results (isError text the model can read and recover from), never thrown to crash the session.
  • Messages are actionable ("filter[x] is required") and never leak secrets — no tokens, API keys, or full auth headers in output or logs.

7. Auth, permissions, safety

  • If tiered (read/write/destructive), disallowed tools should be invisible in tools/list and re-checked at call time (defense in depth).
  • Rate-limit / quota behavior is surfaced, not a silent hang.
  • Secrets come from env/config, never hardcoded; logs use labels/hashes.

Output

A prioritized list, most severe first, grouped by dimension. Each finding:

[dimension] path:line
Problem: <one sentence>
Fix: <concrete change>

End with a 3-line summary: biggest risk, quickest win, and overall design verdict (sharp / serviceable / needs-restructure). Offer to apply the top fixes only if the user asks — review first, edit second.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 1 of the 12 instructions most review quality skills give in 768 tokens

Counted across 1,273 of the 2,403 authors here whose files we hold, read 2026-09-06

  • Ask one question at a timein 63 of 1273, across 62 files
  • Provide a recommended answer for each questionin 47 of 1273, across 45 files
  • Rank findings by severityin 44 of 1273
  • Use parameterized queries for database accessin 38 of 1273, across 20 files
  • Validate all user input with schemashere, and in 33 of 1273, across 15 files
  • Store secrets in environment variablesin 32 of 1273, across 14 files
  • Explore the codebase to answer questionsin 31 of 1273, across 29 files
  • Store tokens in httpOnly cookiesin 30 of 1273, across 12 files
  • Implement rate limiting on API endpointsin 30 of 1273, across 12 files
  • Sanitize user-provided HTMLin 29 of 1273, across 11 files
  • Return generic error messages to usersin 28 of 1273, across 10 files
  • Cite file and line for every findingin 28 of 1273, across 25 files

Said here and by no other author read

  • Locate tool registration and handlers
  • Review tool granularity and surface area
  • Verify verb-first consistent tool naming
  • Ensure descriptions state purpose and return values
  • Enforce pagination and summary fields for list tools
  • Return errors as tool results

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.