MCP Server Development

Use This Skill When

• Building new MCP servers to integrate external APIs
• Designing tools for LLM agents to use
• Creating workflows that automate external service interactions
• Integrating third-party services for AI access
• Developing domain-specific protocol servers

When NOT to Use

• Simple API wrapper (consider if MCP overhead justified)
• Systems without external service integration
• Runtime debugging of MCP servers (use logs first)

Context: MCP Server Quality Maturity

Undeveloped: Simple API passthrough, overwhelming tool output, confusing tool names.

Target: Well-scoped tools, clear parameter validation, readable responses, consistent naming.

Optimized: Multi-step workflows, error recovery, cost awareness, LLM-optimized information density.

Core Principle

Design for agent workflows, not just APIs. MCP servers succeed when tools match how agents think about problems, surface actionable information, and guide agents toward correct usage patterns.

Instructions

Phase 1: Research and Design

Study MCP protocol:

• Fetch docs: https://modelcontextprotocol.io/llms-full.txt
• Understand tools, resources, prompts, sampling

Define agent-centric tool design:

Principle	Example
Workflows not endpoints	Tool: "schedule_meeting" that checks availability + creates event (not separate tools)
Limited context	Return name+id (not full record); provide "concise" vs "detailed" modes
Actionable errors	"Try filter='active' to reduce results" (not just "invalid parameter")
Natural naming	"schedule_meeting" (not "create_calendar_event_with_availability_check")

Phase 2: Implementation

Choose framework:

Framework	Language	When to Use
FastMCP	Python	Quick prototyping, existing Python APIs
MCP SDK	Node.js/TypeScript	Production servers, complex workflows

FastMCP example:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-service")

@mcp.tool()
def get_weather(city: str, units: str = "fahrenheit") -> str:
    """Get current weather for a city."""
    # Implementation
    return f"Weather in {city}: 72°F, sunny"

if __name__ == "__main__":
    mcp.run()

Phase 3: Tool Design Best Practices

Design tools for agents:

## Tool Design Checklist

**Clear Purpose**:
- [ ] Tool name describes the action (verb-first)
- [ ] Description fits in 1 sentence
- [ ] Single responsibility (focused outcome)

**Useful Parameters**:
- [ ] Required params only (optional params rarely used by agents)
- [ ] Clear parameter descriptions
- [ ] Validation with helpful error messages
- [ ] Default values where sensible

**Actionable Output**:
- [ ] Return essential information (not exhaustive data)
- [ ] Structure response for parsing (JSON, not freetext)
- [ ] Include status indicators (success/failure, warnings)
- [ ] Provide "what's next" in errors

Example tool:

@mcp.tool()
def search_documents(
    query: str,
    limit: int = 10,
    filter_type: str = "all"
) -> dict:
    """Search internal documents.
    
    Args:
        query: Search terms
        limit: Max results (reduces context)
        filter_type: 'all', 'archived', 'recent'
    
    Returns:
        Structured results with score and metadata
    """
    # Implementation ensures response is concise
    return {
        "query": query,
        "found": 42,
        "results": [
            {"title": "...", "score": 0.95, "id": "doc-123"},
            # ...limited to 10
        ],
        "hint": "Try filter_type='recent' if results are stale"
    }

Phase 4: Evaluation-Driven Development

Test with actual agent use:

## Evaluation Scenarios

**Scenario 1: Basic Workflow**
- Agent: "Find documents about Q4 planning"
- Tools needed: search_documents
- Success metric: Agent gets useful results in 1 call

**Scenario 2: Multi-Step Workflow**
- Agent: "Schedule meeting with availability check"
- Tools needed: check_availability, schedule_meeting
- Success metric: Meeting created without errors

**Scenario 3: Error Recovery**
- Agent: "Search with typo query"
- Tool: Returns helpful error + suggestion
- Success metric: Agent corrects query and retries

Iterate based on results:

• Did agent find right tool?
• Did tool parameters match expectations?
• Was output format helpful?
• Did agent need multiple calls or one?

Phase 5: Documentation and Testing

Document thoroughly:

• Tool descriptions (agent-readable)
• Parameter constraints
• Example calls
• Common error scenarios

Test coverage:

• Happy path (normal operation)
• Invalid inputs (malformed params)
• External service failures (API down)
• Rate limiting (responses)

Output

Deliver MCP server with:

1. Tool Design Doc (purpose, parameters, output format)
2. Implementation (FastMCP or SDK)
3. Evaluation Report (agent test scenarios)
4. Documentation (setup, usage, troubleshooting)