MCP Server Development Guide

Use this skill when designing, implementing, or evaluating an MCP server for an external API or service. Keep the main workflow short, then load the detailed reference that matches the implementation language or evaluation task.

Load First

• MCP protocol: fetch https://modelcontextprotocol.io/llms-full.txt
• MCP best practices
• Python SDK docs: fetch https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• TypeScript SDK docs: fetch https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Workflow

1. Research and Plan

• Read the target service API docs: auth, rate limits, pagination, errors, endpoints, schemas, and destructive operations.
• Design workflow-level tools instead of thin endpoint wrappers.
• Prefer high-signal outputs, stable human-readable IDs, and explicit concise or detailed response modes.
• Plan shared request helpers, pagination, formatting, input validation, authentication, and actionable error messages before writing tools.
• Mark read-only, destructive, idempotent, and open-world behavior with MCP tool annotations where supported.

2. Implement

For Python, load Python implementation guide. Use the MCP Python SDK, Pydantic models, type hints, async I/O for external calls, shared helpers, and clear module-level constants.

For Node/TypeScript, load TypeScript implementation guide. Use the MCP TypeScript SDK, strict TypeScript, Zod schemas, explicit return types, and a working build script.

For every tool:

• Use schema validation with useful constraints and examples.
• Write descriptions that explain when to use the tool, expected inputs, output shape, and recovery steps for common errors.
• Keep tool outputs bounded and predictable; paginate or summarize large data.
• Return errors as actionable tool results when the agent can recover.

3. Review and Test

• Check for duplicated code, inconsistent output formats, weak validation, and generic exceptions.
• Do not run long-lived stdio MCP servers directly in the main terminal without a timeout or harness.
• Python smoke checks: python -m py_compile server.py, then run the evaluation harness or a short timeout test.
• TypeScript smoke checks: npm run build, confirm dist/ output, then run the evaluation harness or a short timeout test.
• Use the quality checklist in the language guide before handing off.

4. Evaluate

Load evaluation guide to create read-only, verifiable questions and run the bundled harness.

Run the harness with its dependencies from the skill directory:

uv run --with 'mcp>=2,<3' --with 'anthropic>=0.39.0' --with 'openai>=1.0.0' -- python scripts/evaluation.py --help

Provider examples:

# Claude provider
ANTHROPIC_API_KEY=... uv run --with 'mcp>=2,<3' --with 'anthropic>=0.39.0' --with 'openai>=1.0.0' -- python scripts/evaluation.py \
  -t stdio -c python -a my_server.py evaluation.xml

# OpenAI-compatible provider
OPENAI_API_KEY=... uv run --with 'mcp>=2,<3' --with 'anthropic>=0.39.0' --with 'openai>=1.0.0' -- python scripts/evaluation.py --provider openai \
  -t stdio -c python -a my_server.py evaluation.xml

# Emulation provider, no LLM key
uv run --with 'mcp>=2,<3' -- python scripts/evaluation.py --provider emulation \
  --emulation-script assets/smoke_emulation.json \
  -t stdio -c python -a my_server.py assets/smoke_eval.xml

The evaluation XML format is:

<evaluation>
  <qa_pair>
    <question>Question that requires read-only tool use.</question>
    <answer>Stable expected answer.</answer>
  </qa_pair>
</evaluation>

Reference Library

• MCP best practices: universal design, naming, response, pagination, security, and error-handling guidance.
• Python implementation guide: MCPServer examples, Pydantic patterns, resources, prompts, and quality checklist.
• TypeScript implementation guide: SDK server structure, Zod patterns, tool registration, build setup, and checklist.
• Evaluation guide: question design, XML format, harness setup, providers, reporting, and troubleshooting.