mcp-development
Original：🇺🇸 English
Translated
Use when building "MCP server", "Model Context Protocol", creating "Claude tools", "MCP tools", or asking about "FastMCP", "MCP SDK", "tool development for LLMs", "external API integration for Claude"
5installs
Sourceeyadsibai/ltk
Added on
NPX Install
npx skill4agent add eyadsibai/ltk mcp-developmentTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →MCP Server Development Guide
Build high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services.
Core Design Principles
Build for Workflows, Not Just APIs
| Principle | Why |
|---|---|
| Consolidate operations | Single tool for complete tasks |
| Return high-signal data | Agents have limited context |
| Provide format options | "concise" vs "detailed" modes |
| Use human-readable IDs | Not technical codes |
| Make errors actionable | Guide toward correct usage |
Key concept: Don't just wrap API endpoints. Design tools that enable complete workflows agents actually need.
Development Phases
Phase 1: Research
| Step | Action |
|---|---|
| Study MCP Protocol | Read |
| Study SDK docs | Python or TypeScript SDK README |
| Study target API | Read ALL available documentation |
| Create implementation plan | Before writing code |
Phase 2: Design
| Decision | Options |
|---|---|
| Language | Python (FastMCP) or TypeScript |
| Tool granularity | Atomic vs workflow-oriented |
| Response format | JSON, Markdown, or both |
| Error handling | What errors can occur, how to recover |
Phase 3: Implementation
| Component | Purpose |
|---|---|
| Input validation | Pydantic (Python) or Zod (TypeScript) |
| Tool descriptions | Clear, with examples |
| Error messages | Include suggested next steps |
| Response formatting | Consistent across tools |
Phase 4: Testing
Critical: MCP servers are long-running processes. Never run directly in main process.
| Approach | How |
|---|---|
| Evaluation harness | Recommended |
| tmux session | Run server separately |
| Timeout wrapper | |
| MCP Inspector | Official debugging tool |
Tool Annotations
| Annotation | Meaning | Default |
|---|---|---|
| readOnlyHint | Doesn't modify state | false |
| destructiveHint | Can cause damage | true |
| idempotentHint | Repeated calls safe | false |
| openWorldHint | Interacts externally | true |
Key concept: Annotations help the LLM decide when and how safely to use tools.
Input Design
Validation Patterns
| Pattern | Use Case |
|---|---|
| Required fields | Core parameters |
| Optional with defaults | Convenience parameters |
| Enums | Limited valid values |
| Min/max constraints | Numeric bounds |
| Pattern matching | Format validation (email, URL) |
Parameter Naming
| Good | Bad | Why |
|---|---|---|
| | Self-documenting |
| | Concise but clear |
| | Descriptive boolean |
Response Design
Format Options
| Format | Use Case |
|---|---|
| JSON | Programmatic use, structured data |
| Markdown | Human readability, reports |
| Hybrid | JSON in markdown code blocks |
Response Guidelines
| Guideline | Why |
|---|---|
| ~25,000 token limit | Context constraints |
| Truncate with indicator | Don't silently cut |
| Support pagination | |
| Include metadata | Total count, has_more |
Error Handling
Error Message Structure
| Element | Purpose |
|---|---|
| What failed | Clear description |
| Why it failed | Root cause if known |
| How to fix | Suggested next action |
| Example | Correct usage |
Key concept: Error messages should guide the agent toward correct usage, not just diagnose problems.
Quality Checklist
Code Quality
| Check | Description |
|---|---|
| No duplicated code | Extract shared logic |
| Consistent formats | Similar ops return similar structure |
| Full error handling | All external calls wrapped |
| Type coverage | All inputs/outputs typed |
| Comprehensive docstrings | Every tool documented |
Tool Quality
| Check | Description |
|---|---|
| Clear descriptions | Model knows when to use |
| Good examples | In docstring |
| Sensible defaults | Reduce required params |
| Consistent naming | Group related with prefixes |
Best Practices
| Practice | Why |
|---|---|
| One tool = one purpose | Clear mental model |
| Comprehensive descriptions | LLM selection accuracy |
| Include examples in docstrings | Show expected usage |
| Return actionable errors | Enable self-correction |
| Test with actual LLM | Real-world validation |
| Version your server | Track compatibility |
Resources
- MCP Protocol: https://modelcontextprotocol.io/
- Python SDK: https://github.com/modelcontextprotocol/python-sdk
- TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk