creating-mcp-servers
Creates production-ready MCP servers using FastMCP v2. Use when building MCP servers, optimizing tool descriptions for context efficiency, implementing progressive disclosure for multiple capabilities, or packaging servers for distribution.
Install
npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/development-tools/skills/creating-mcp-servers
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
git clone https://github.com/oaustegard/claude-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.
README
creating-mcp-servers
Creates production-ready MCP servers using FastMCP v2. Use when building MCP servers, optimizing tool descriptions for context efficiency, implementing progressive disclosure for multiple capabilities, or packaging servers for distribution.
Skill manifest
Creating MCP Servers
Build production-ready MCP servers using FastMCP v2 with optimal context efficiency through progressive disclosure patterns.
Core Capabilities
- Apply the core patterns - Four requirements for consistency
- Implement progressive disclosure - Gateway patterns achieving 85-93% token reduction
- Optimize tool descriptions - 65-70% token reduction through proper patterns
- Bundle servers - Package as MCPB files with validation
- Proven gateway patterns - Three complete implementations (Skills, API, Query)
Architecture Decision
1-3 simple tools?
→ Standard FastMCP with optimized tools
Load: references/MANDATORY_PATTERNS.md
5+ related capabilities?
→ Gateway pattern (progressive disclosure)
Load: references/PROGRESSIVE_DISCLOSURE.md
Load: references/GATEWAY_PATTERNS.md
Optimize existing server?
→ Apply mandatory patterns
Load: references/MANDATORY_PATTERNS.md
Package for distribution?
→ MCPB bundler
Load: references/MCPB_BUNDLING.md
Execute: scripts/create_mcpb.py
Need FastMCP documentation?
→ Search references/LLMS_TXT.md for relevant URLs
→ Use web_fetch on gofastmcp.com URLs
Mandatory Patterns (Summary)
Every implementation should meet these four requirements:
- uv (never pip) -
uv pip install fastmcp - Optimized tool descriptions - Annotations, Annotated, concise docstrings
- Authoritative documentation - Fetch from gofastmcp.com via LLMS_TXT.md index
- Apply all patterns - Every implementation meets verification checklist
Details in references/MANDATORY_PATTERNS.md
Documentation Retrieval Workflow
To fetch FastMCP documentation:
1. Read references/LLMS_TXT.md - complete URL index
2. Search for relevant topic keywords
3. Use web_fetch on matched URLs (append .md for markdown)
4. Apply patterns from fetched documentation
Example: Authentication patterns → Search LLMS_TXT.md for "authentication" → web_fetch https://gofastmcp.com/servers/auth/authentication.md
Progressive Disclosure Pattern
For servers with 5+ capabilities:
Three-tier loading:
- Metadata (~20 tokens/capability) - Always loaded
- Content (~500 tokens) - Load on demand
- Execution (0 tokens) - Execute without loading
Achieves 85-93% baseline reduction. See references/PROGRESSIVE_DISCLOSURE.md
Implementation Phases
Phase 1: Research
Read LLMS_TXT.md → Find relevant URLs → web_fetch documentation
Phase 2: Implement
Load appropriate reference based on architecture decision. Apply all four patterns.
Phase 3: Package (Optional)
cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/
See references/MCPB_BUNDLING.md for manifest format.
Reference Library
Documentation index (load first for FastMCP knowledge):
- LLMS_TXT.md - Complete FastMCP v2 documentation URLs
Core patterns:
- MANDATORY_PATTERNS.md - the four core requirements
- PROGRESSIVE_DISCLOSURE.md - Architecture for 5+ capabilities
Implementation:
- GATEWAY_PATTERNS.md - Three production-ready implementations
- MCPB_BUNDLING.md - Packaging and distribution
Scripts:
scripts/create_mcpb.py- Bundle MCP servers into .mcpb files
Verification Checklist
Before completing any FastMCP implementation:
✓ Uses uv (not pip)
✓ FastMCP docs fetched from LLMS_TXT.md URLs (not web_search)
✓ Tool annotations (readOnlyHint, title, openWorldHint)
✓ Annotated parameters with Field
✓ Single-sentence docstrings
✓ 65-70% token reduction vs verbose
✓ Server instructions concise (<100 chars)
For gateway implementations, additionally verify:
✓ 85%+ baseline context reduction
✓ Discover returns metadata only
✓ Load fetches content on demand
✓ Execute runs without context cost
Tool Description Pattern
Before (180 tokens):
@mcp.tool()
async def search_items(query: str):
"""Search for items in the database.
This tool allows comprehensive searching..."""
After (55 tokens):
@mcp.tool(
annotations={"title": "Search", "readOnlyHint": True, "openWorldHint": False}
)
async def search_items(
query: Annotated[str, Field(description="Search text")],
ctx: Context = None
):
"""Search items. Fast full-text search across all fields."""
Common Pitfalls
❌ Using mcpb pack CLI (causes crashes, just use zip)
❌ Using pip instead of uv
❌ web_search for FastMCP docs (use web_fetch on LLMS_TXT.md URLs)
❌ Verbose tool descriptions
❌ Missing tool annotations
❌ Gateway for 1-3 tools (overhead exceeds benefit)
❌ Mixing unrelated capabilities in single gateway
Files (claude-skills)
-
references
-
GATEWAY_PATTERNS.md 14.9 KB
Loading… -
LLMS_TXT.md 20.2 KB
Loading… -
MANDATORY_PATTERNS.md 6.5 KB
Loading… -
MCPB_BUNDLING.md 4.6 KB
Loading… -
PROGRESSIVE_DISCLOSURE.md 6.8 KB
Loading…
-
-
scripts
-
create_mcpb.py 11.5 KB
Loading…
-
-
CHANGELOG.md 904 B
Loading… -
README.md 265 B
# creating-mcp-servers Creates production-ready MCP servers using FastMCP v2. Use when building MCP servers, optimizing tool descriptions for context efficiency, implementing progressive disclosure for multiple capabilities, or packaging servers for distribution. -
SKILL.md 5.2 KB
--- name: creating-mcp-servers description: Creates production-ready MCP servers using FastMCP v2. Use when building MCP servers, optimizing tool descriptions for context efficiency, implementing progressive disclosure for multiple capabilities, or packaging servers for distribution. metadata: version: 1.2.0 --- # Creating MCP Servers Build production-ready MCP servers using FastMCP v2 with optimal context efficiency through progressive disclosure patterns. ## Core Capabilities 1. **Apply the core patterns** - Four requirements for consistency 2. **Implement progressive disclosure** - Gateway patterns achieving 85-93% token reduction 3. **Optimize tool descriptions** - 65-70% token reduction through proper patterns 4. **Bundle servers** - Package as MCPB files with validation 5. **Proven gateway patterns** - Three complete implementations (Skills, API, Query) ## Architecture Decision ``` 1-3 simple tools? → Standard FastMCP with optimized tools Load: references/MANDATORY_PATTERNS.md 5+ related capabilities? → Gateway pattern (progressive disclosure) Load: references/PROGRESSIVE_DISCLOSURE.md Load: references/GATEWAY_PATTERNS.md Optimize existing server? → Apply mandatory patterns Load: references/MANDATORY_PATTERNS.md Package for distribution? → MCPB bundler Load: references/MCPB_BUNDLING.md Execute: scripts/create_mcpb.py Need FastMCP documentation? → Search references/LLMS_TXT.md for relevant URLs → Use web_fetch on gofastmcp.com URLs ``` ## Mandatory Patterns (Summary) Every implementation should meet these four requirements: 1. **uv (never pip)** - `uv pip install fastmcp` 2. **Optimized tool descriptions** - Annotations, Annotated, concise docstrings 3. **Authoritative documentation** - Fetch from gofastmcp.com via LLMS_TXT.md index 4. **Apply all patterns** - Every implementation meets verification checklist Details in [references/MANDATORY_PATTERNS.md](references/MANDATORY_PATTERNS.md) ## Documentation Retrieval Workflow **To fetch FastMCP documentation:** ``` 1. Read references/LLMS_TXT.md - complete URL index 2. Search for relevant topic keywords 3. Use web_fetch on matched URLs (append .md for markdown) 4. Apply patterns from fetched documentation ``` **Example:** Authentication patterns → Search LLMS_TXT.md for "authentication" → web_fetch https://gofastmcp.com/servers/auth/authentication.md ## Progressive Disclosure Pattern For servers with 5+ capabilities: **Three-tier loading:** 1. Metadata (~20 tokens/capability) - Always loaded 2. Content (~500 tokens) - Load on demand 3. Execution (0 tokens) - Execute without loading Achieves 85-93% baseline reduction. See [references/PROGRESSIVE_DISCLOSURE.md](references/PROGRESSIVE_DISCLOSURE.md) ## Implementation Phases ### Phase 1: Research Read LLMS_TXT.md → Find relevant URLs → web_fetch documentation ### Phase 2: Implement Load appropriate reference based on architecture decision. Apply all four patterns. ### Phase 3: Package (Optional) ```bash cd /home/claude zip -r server-name.mcpb manifest.json server.py README.md cp server-name.mcpb /mnt/user-data/outputs/ ``` See [references/MCPB_BUNDLING.md](references/MCPB_BUNDLING.md) for manifest format. ## Reference Library **Documentation index (load first for FastMCP knowledge):** - [LLMS_TXT.md](references/LLMS_TXT.md) - Complete FastMCP v2 documentation URLs **Core patterns:** - [MANDATORY_PATTERNS.md](references/MANDATORY_PATTERNS.md) - the four core requirements - [PROGRESSIVE_DISCLOSURE.md](references/PROGRESSIVE_DISCLOSURE.md) - Architecture for 5+ capabilities **Implementation:** - [GATEWAY_PATTERNS.md](references/GATEWAY_PATTERNS.md) - Three production-ready implementations - [MCPB_BUNDLING.md](references/MCPB_BUNDLING.md) - Packaging and distribution **Scripts:** - `scripts/create_mcpb.py` - Bundle MCP servers into .mcpb files ## Verification Checklist Before completing any FastMCP implementation: ``` ✓ Uses uv (not pip) ✓ FastMCP docs fetched from LLMS_TXT.md URLs (not web_search) ✓ Tool annotations (readOnlyHint, title, openWorldHint) ✓ Annotated parameters with Field ✓ Single-sentence docstrings ✓ 65-70% token reduction vs verbose ✓ Server instructions concise (<100 chars) ``` For gateway implementations, additionally verify: ``` ✓ 85%+ baseline context reduction ✓ Discover returns metadata only ✓ Load fetches content on demand ✓ Execute runs without context cost ``` ## Tool Description Pattern **Before (180 tokens):** ```python @mcp.tool() async def search_items(query: str): """Search for items in the database. This tool allows comprehensive searching...""" ``` **After (55 tokens):** ```python @mcp.tool( annotations={"title": "Search", "readOnlyHint": True, "openWorldHint": False} ) async def search_items( query: Annotated[str, Field(description="Search text")], ctx: Context = None ): """Search items. Fast full-text search across all fields.""" ``` ## Common Pitfalls ❌ Using `mcpb pack` CLI (causes crashes, just use `zip`) ❌ Using pip instead of uv ❌ web_search for FastMCP docs (use web_fetch on LLMS_TXT.md URLs) ❌ Verbose tool descriptions ❌ Missing tool annotations ❌ Gateway for 1-3 tools (overhead exceeds benefit) ❌ Mixing unrelated capabilities in single gateway
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.