mcp-server-design
Made by JeffDesign agent-friendly MCP servers with optimal UX. Use when building MCP tools, designing agent APIs, writing tool documentation, implementing error handling, or creating multi-agent coordination systems.
Works With
Quality and Utility come from canonical skill metadata. Community ratings appear separately as stars when subscriber reviews exist.
Subscribe to download
Public previews are available, but downloads, CLI sync, and premium content require an active subscription.
Sign In to Subscribe- Full skill content with deterministic versioning
- CLI sync + local search index
- Access to Jeffrey’s premium library
Save to your account
Saved skills live in your cloud list. Run jsm sync on each machine to pull them locally.
What's New with this Skill
2Updates, enhancements, and release notes for this skill.
Updated: mcp-server-design, installers write the config files clients actually read
The installation scripts registered servers in claude_desktop_config.json, which Claude Code does not read, and wrote invalid hook JSON. The resource examples used methods the low-level MCP Server lacks, and required non-URI arguments make FastMCP raise at registration. All are fixed against fastmcp 2.13, mcp 1.25 and the Claude Code and Codex CLIs.
- Claude Code reads MCP servers from ~/.claude.json or .mcp.json, not claude_desktop_config.json
- Codex servers live in ~/.codex/config.toml under [mcp_servers.<name>]
- Hook injection now writes the matcher/hooks group format Claude Code accepts
- Resource templates use FastMCP's {?a,b} query syntax so registration does not raise
- Client configs. Claude Code reads user and local servers from
~/.claude.jsonand project servers from.mcp.json;claude_desktop_config.jsonbelongs to Claude Desktop. The skill now recommendsclaude mcp add --scope user. Codex uses~/.codex/config.tomlwith[mcp_servers.<name>](orcodex mcp add), Cursor~/.cursor/mcp.json, Gemini CLI~/.gemini/settings.json. - Hook injection. Both installers wrote hook config in shapes Claude Code rejects; they now write
{matcher, hooks: [{type, command}]}groups.
New: MCP Server Design, make the wrong thing impossible and the right thing obvious
Agents are not humans. They infer parameter meanings from names, retry identical calls after an error, and confuse program names (claude-code, cursor) with agent identities. A tool surface that's polite to a human is hostile to an agent. The skill is 12 codified principles, the ToolExecutionError shape, six mistake detectors, and 65+ patterns across 17 reference files for designing tools agents can actually use.
- The One Rule: make the wrong thing impossible and the right thing obvious. Every design decision passes through this filter
- 12 codified principles: Anticipate Intent, Fail Helpfully, Intercept Early, Forgive by Default, Document for Agents, Scope Narrowly (no broadcast), Provide Macros, Precision Over Breadth (≤7 tools per cluster), Workflow-First, Defense in Depth, Full Observability, Graceful Degradation
- ToolExecutionError(error_type, message, recoverable, data) is the only error shape. Each carries a machine-parseable type (BROADCAST_ATTEMPT, NOT_FOUND, FILE_RESERVATION_CONFLICT, EMFILE…), a human message, a retry hint, and a data payload with suggestions, fix_hint, available_options
- Six mistake detectors per parameter: program name, model name, email as identity, broadcast keywords, descriptive suffixes (agent/bot/worker/handler), Unix username. Placeholder strings (YOUR_PROJECT, $PROJECT) get a separate check
- Three enforcement modes (strict/coerce/always_auto) with coerce as the default. Timestamps auto-coerce slashes → dashes and Z → +00:00; FTS5 queries strip leading wildcards; pre-computed frozensets give O(1) validation
- Fake CLI stub for agents who try to invoke an MCP server from the shell: the stub and its dash/underscore/lowercase symlinks print a banner pointing to the real MCP tools and exit 1
- 14+ discovery resources: resource://projects, resource://agents/{key}, resource://views/urgent-unread/{agent}, resource://views/ack-required/{agent}, and more. Agents read resources without a tool round-trip
- Four macros bundle the common multi-step flows for smaller models: macro_start_session (ensure project + register agent + fetch inbox), macro_prepare_thread, macro_file_reservation_cycle, macro_contact_handshake. Returns next_actions hints
- No broadcast, as a hard rule: recipient "all" raises BROADCAST_ATTEMPT with available_recipients in the data payload. Targeted messages keep other agents' context clean
- Test with Haiku as a canary for unclear APIs: if a smaller model can use the tool, larger models can. Plus 13 XSS attack categories, path-traversal tests, and advisory-semantics tests for file-reservation race conditions
The One Rule: make the wrong thing impossible and the right thing obvious. Every design decision passes through one filter: if an agent makes an obvious mistake, does this educate them or just fail?
The principles are codified, not abstract. Anticipate Intent: detect what the agent MEANT, not just what they said. Fail Helpfully: every error returns ToolExecutionError(error_type, message, recoverable, data) with structured suggestions and discovery hints, never a stack trace. Forgive by Default: three enforcement modes (strict rejects with detail, coerce auto-fixes and is the default, `a