Wardn HubTrusted MCP server directory.

Registry

  • MCP Servers
  • Skills
  • Categories

Resources

  • API docs
  • Score method

Contribute

  • Submit server
  • Advertise
© 2026 Wardn Hub
Wardn Hub
MCP ServersSkillsCategoriesAPI docsSubmit server
Submit server
skills/mohitagw15856/pm-claude-skills/mcp-server-spec

mcp-server-spec

1
mohitagw15856/pm-claude-skills·Audit passed·Snapshot 445cc4e13821

Summary

This source did not publish a separate summary. Review SKILL.md before using the skill.

SKILL.md

MCP Server Spec Skill

Every SaaS is shipping an MCP server; most dump their REST API as forty tools and wonder why agents flail. This skill designs the server as what it actually is: a user interface for a non-human user — few tools, task-shaped, with descriptions written for a model deciding under uncertainty.

What This Skill Produces

  • A toolset design: 3-10 tools mapped to agent tasks, not API endpoints
  • Per-tool specs: name, description (the routing surface), parameters, returns, error behaviour
  • Auth & scoping decisions: how credentials flow, what a token can never do
  • An explicit not-exposed list with reasons — the most load-bearing section
  • A test plan: the agent-eval loop that proves the toolset works

Required Inputs

Ask for (if not already provided):

  • The product and what users hire it for (the top 5 jobs, not the feature list)
  • The existing API surface (endpoints or capability list) if one exists
  • Who the agent acts for — the end user's own account? a service account? multi-tenant?
  • The riskiest actions the product supports (deletes, sends, payments, permission changes)

Design Method

  1. Start from agent tasks, not endpoints. List the 5-8 things an agent will actually be asked to do with this product ("file an expense", "find last quarter's report", "summarise ticket history"). Each becomes one tool — even if it spans four API calls internally. An endpoint-mirrored toolset makes the agent do your orchestration; a task-shaped one does it for them.
  2. Keep the toolset small. Every tool dilutes selection accuracy on every call. Target ≤10; past ~15, split into separately-loadable servers by workflow. Merge list/get/search variants behind one tool with parameters where natural.
  3. Write descriptions as routing surfaces. The description is all the model sees when choosing. Formula per tool: what it does (one clause) · when to use it · what it returns. Test: could a model pick correctly between your two closest tools from descriptions alone?
and when to use the sibling tool instead
  • Design returns for context windows. Return the 6 fields an agent needs, not the 60 the API has; include stable IDs for chaining; paginate with explicit has_more; keep any response under ~2k tokens by default with an opt-in for detail.
  • Make errors instructive. An agent retries what it understands: "date must be YYYY-MM-DD" beats 400 Bad Request. Every error names the parameter at fault and the fix.
  • Draw the safety boundary. Classify every capability: expose (read/create, low blast radius) · expose gated (destructive/outward-facing — require an explicit confirmation parameter and document that clients should surface approval) · never expose (auth changes, deletes without recovery, bulk exports of other users' data). The never-list ships in the spec with reasons.
  • Specify auth honestly. OAuth per end user (agent acts as the user, inherits their permissions) vs API key (service account — then per-tool scoping matters more). State token lifetime, revocation, and what happens mid-session on expiry.

    • Output Format

    MCP Server Spec: [product]

    Agent jobs served: [the 5-8 tasks] · Tool count: [n] · Auth: [model + scoping]

    Tools

    ToolDescription (as shipped)Key paramsReturnsRisk class

    Gated actions: [which tools require confirmation params, and the expected client behaviour]

    Never exposed: [capability → reason] (one line each; this list is reviewed like an API contract)

    Error design: [the error shape + 3 example messages]

    Test plan: [10-15 realistic agent prompts spanning the jobs; run against a real client; a tool whose description gets misselected twice gets rewritten, not documented around]

    Quality Checks

    • Every tool maps to an agent task; no tool exists because "the endpoint was there"
    • Any two sibling tools are distinguishable from their descriptions alone
    • Default responses fit comfortably in a context window (≤~2k tokens)
    • Every destructive or outward-facing action is gated or on the never-list
    • Errors name the offending parameter and the fix
    • The spec includes the agent-eval test plan, not just the schema

    Anti-Patterns

    • Do not mirror the REST API — 40 endpoint-tools is the #1 way MCP servers fail
    • Do not write descriptions for developers ("wraps the /v2/items endpoint") — write them for a model choosing a tool
    • Do not return full API payloads — context windows are the scarce resource
    • Do not expose destructive actions ungated because "the client will be careful"
    • Do not skip the never-exposed list — an MCP server without one hasn't been threat-modelled
    • Do not ship without running the agent test plan — schema-valid and agent-usable are different properties

    Related skills

    capacity-planningcompetitor-teardowncontext-engineering-reviewrunbook-writerreceipts-audit