Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
allowed-tools
Bash(uv run * scripts/connections.py *) Bash(uv run * scripts/evaluation.py *) Bash, Read, Write, Edit, Glob, Grep
argument-hint
service name or spec to build an MCP server for (e.g. "GitHub REST API" or "my Postgres database")
Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
Process
🚀 High-Level Workflow
Creating a high-quality MCP server involves four main phases:
Phase 1: Deep Research and Planning
1.1 Understand Modern MCP Design
API Coverage vs. Workflow Tools:
Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.
Tool Naming and Discoverability:
Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.
Context Management:
Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.
Actionable Error Messages:
Error messages should guide agents toward solutions with specific suggestions and next steps.
1.2 Study MCP Protocol Documentation
Navigate the MCP specification:
Start with the sitemap to find relevant pages: https://modelcontextprotocol.io/sitemap.xml
Then fetch specific pages with .md suffix for markdown format (e.g., https://modelcontextprotocol.io/specification/draft.md).
Key pages to review:
Specification overview and architecture
Transport mechanisms (streamable HTTP, stdio)
Tool, resource, and prompt definitions
1.3 Study Framework Documentation
Recommended stack:
Language: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
Transport: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers.
Understand the API:
Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.
Tool Selection:
Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.
Answer Verification: Solve each question yourself to verify answers
4.3 Evaluation Requirements
Ensure each question is:
Independent: Not dependent on other questions
Read-only: Only non-destructive operations required
Complex: Requiring multiple tool calls and deep exploration
Realistic: Based on real use cases humans would care about
Verifiable: Single, clear answer that can be verified by string comparison
Stable: Answer won't change over time
4.4 Output Format
Create an XML file with this structure:
<evaluation><qa_pair><question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question><answer>3</answer></qa_pair><!-- More qa_pairs... --></evaluation>
Tool Design for Agent Consumers
When building an MCP server, the tool API is a contract with LLM agents, not with human developers. Agent cognition differs from human cognition in ways that require different design principles.
The Consolidation Principle
If a human engineer can't immediately decide which tool to use in a given situation, an agent can't either.
This is the single most important principle. Tool overlap creates decision paralysis in agents. Signs of over-fragmentation:
Multiple tools for reading vs. searching the same data
Separate tools for "get" vs. "list" that differ only in scope
Overlapping names with ambiguous differentiation
Practical ceiling: 10-20 tools per server. Beyond 20, agents make statistically more tool selection errors.
Description Engineering
Every tool description must answer four questions. If any are missing, agents will misuse the tool:
@mcp.tooldefsearch_documents(
query: str,
collection: str = "default",
limit: int = 10) -> list[dict]:
"""
[WHAT] Performs semantic similarity search over indexed documents.
[WHEN] Use when you need to find documents by meaning or concept,
not exact text match. Use grep_documents for exact string search.
[RETURNS] List of {id, content, score, metadata} dicts ordered by
relevance. Empty list if no matches above threshold 0.7.
[ERRORS] Raises CollectionNotFoundError if collection doesn't exist.
Use list_collections first if unsure.
"""
Architectural Reduction
The most counter-intuitive principle: sometimes fewer, more primitive tools outperform elaborate specialized tools. Reasons:
Models have strong priors for filesystem operations and shell commands
Specialized tools introduce abstraction that the model must first learn to pierce
Direct access + good naming conventions achieves the same goal with less cognitive overhead
Ask before adding a specialized tool: does this enable new capabilities, or does it just constrain reasoning the model could handle with bash/filesystem access?
Naming Conventions
Always use fully-qualified names in MCP: ServerName:tool_name. Without the server prefix, agents fail when multiple MCP servers are active.
# Correct (fully qualified)
server = FastMCP("DataStore") # tools exposed as DataStore:search, DataStore:write# Correct tool naming pattern# Verb + noun: search_documents, write_record, delete_entry, list_collections# NOT: search, get, fetch (too generic — causes collision with other servers)
Anti-Patterns
Anti-pattern
Problem
Fix
Overlapping tools
Agent can't decide which to use
Consolidate; make difference explicit in description
Missing return format
Agent can't parse output
Specify exact schema in description
Vague names (get, fetch, process)
Namespace collision across servers
Use ServerName:get_user_record
No error documentation
Agent loops on error
Document all exception types and recovery path
Too many tools (>20)
Selection error rate spikes
Group into sub-servers; each ≤15 tools
Reference Files
📚 Documentation Library
Load these resources as needed during development:
Core MCP Documentation (Load First)
MCP Protocol: Start with sitemap at https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with .md suffix
