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.
A direct command skips the review prompt. Inspect the source before running it.
Verify each tool's schema validates a real request and rejects malformed input.
Phase 4 โ Evaluation
Write 10 realistic end-user questions that an LLM should be able to answer using your server. Run them through Claude with the server attached. Grade: did the model call the right tool? Did the response give enough to answer? Fix the description, schema, or response format of any tool that failed.
Example eval questions for a github-mcp:
"What issues are open on repo X with label bug?"
"Create an issue titled Y in repo Z"
"Who has the most commits this month in repo X?"
When a tool fails an eval, the cause is almost always the description, not the schema. Score each tool against the description rubric in mcp-patterns (one-line purpose, WHEN TO USE, WHEN NOT TO USE, CRITICAL, self-test). A tool with an empty WHEN NOT TO USE is under-specified โ it will misfire the moment a second tool in the same server overlaps with it, so add the boundary before re-running the eval. See mcp-patterns โ "How to Write a Tool Description" for the full rubric and worked example.
Tool Design Checklist
Name has service prefix and is verb-led
Description mentions when to use it and includes trigger keywords
Description carries a non-empty WHEN NOT TO USE that names overlapping tools (see mcp-patterns rubric)
Input schema is strict, no free-form object with additionalProperties: true
Output is focused โ essential fields only, with pagination cursor if applicable
Error responses are actionable ("API returned 403 โ check GITHUB_TOKEN env var")
Annotations set correctly (readonly/destructive/idempotent)
claude mcp add my-mcp --scope user -- node /path/to/server.js
Claude Desktop: same JSON, placed in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
Common Pitfalls
Mistake
Fix
1:1 API mirror with 80 tools
Pick 10 workflow-oriented tools
description: "wrapper for /users endpoint"
description: "Find users by email, role, or team. Use when the user mentions employees, staff, or access"
Dumping raw JSON responses
Filter to 3-5 fields the agent actually needs
Logging API keys on error
Redact all env vars in error formatters
exit 1 on transient errors
Retry with exponential backoff, surface final error
Stdout pollution (MCP stdio)
All logs go to stderr, stdout is JSON-RPC only
Rules
MUST pick 5-15 workflow-oriented tools, not a 1:1 API mirror. The model routes by task, not by endpoint.
MUST use strict input schemas (Zod for TS, Pydantic for Python). additionalProperties: true lets the model invent fields and drift.
MUST set correct tool annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint โ the host uses these for safety UIs and auto-approval policies
NEVER expose an MCP server on a public network without auth. MCP clients default to trusting the transport โ attackers reach tools directly.
NEVER log API keys, tokens, or env vars in error messages. A verbose error thrown at the model becomes a stored credential in the conversation.
CRITICAL: with stdio transport, all logs go to stderr. Any stdout write that is not a JSON-RPC message breaks the client.
MANDATORY: every server ships with a README documenting env vars, required scopes, rate limits, and a minimal invocation example.
Gotchas
stdio transport sends the server's stdout directly to the client as protocol frames. A stray print() or console.log() crashes the client with a parse error and no clear diagnostic. Route all logs through a logger that writes to stderr.
MCP tool descriptions are the only thing the LLM sees when routing. description: "calls POST /api/v2/tickets" tells the model nothing about intent. Describe when to use, not what it does at the HTTP level.
Annotations (readOnlyHint, etc.) are optional in the spec but some hosts (Claude Desktop, Cursor) gate auto-approval on them. Missing destructiveHint: true on a delete tool may cause the client to run it silently.
streamable-http with SSE requires the server to handle client reconnects with a Last-Event-ID header. Many quick-start templates skip this and drop events on flaky networks.
Pagination cursors must be opaque from the client's perspective but stable across retries. A timestamp cursor that advances on every poll fails if the client retries the same cursor after a transient error.
Claude Desktop caches server capabilities on first connection. After changing tool schemas, users must explicitly reload the server (quit + reopen or remove/re-add the server) โ simply restarting the server process is not enough.
When NOT to Use
For in-toolkit skills (slash commands, knowledge docs) โ use /skill-creator
For agents inside ai-toolkit โ use /agent-creator
For plugin packs bundling multiple agents/skills โ use /plugin-creator
For protocol-level MCP theory and transport trade-offs โ use /mcp-patterns (knowledge skill)
For conformance/integration testing of an MCP server โ delegate to the mcp-testing-engineer agent
