mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when…

installs

stars

karma

view original SKILL.md from skills.shclick to expand

MCP Server Development Guide

Overview

To create high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services, use this skill. An MCP server provides tools that allow LLMs to access external services and APIs. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks using the tools provided.

Process

🚀 High-Level Workflow

Creating a high-quality MCP server involves four main phases:

Phase 1: Deep Research and Planning

1.1 Understand Agent-Centric Design Principles

Before diving into implementation, understand how to design tools for AI agents by reviewing these principles:
Build for Workflows, Not Just API Endpoints:

Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools

Consolidate related operations (e.g., schedule_event that both checks availability and creates event)

Focus on tools that enable complete tasks, not just individual API calls

Consider what workflows agents actually need to accomplish

Optimize for Limited Context:

Agents have constrained context windows - make every token count

Return high-signal information, not exhaustive data dumps

Provide "concise" vs "detailed" response format options

Default to human-readable identifiers over technical codes (names over IDs)

Consider the agent's context budget as a scarce resource

Design Actionable Error Messages:

Error messages should guide agents toward correct usage patterns

Suggest specific next steps: "Try using filter='active_only' to reduce results"

Make errors educational, not just diagnostic

Help agents learn proper tool usage through clear feedback

Follow Natural Task Subdivisions:

Tool names should reflect how humans think about tasks

Group related tools with consistent prefixes for discoverability

Design tools around natural workflows, not just API structure

Use Evaluation-Driven Development:

Create realistic evaluation scenarios early

Let agent feedback drive tool improvements

Prototype quickly and iterate based on actual agent performance

1.3 Study MCP Protocol Documentation

Fetch the latest MCP protocol documentation:

Use WebFetch to load: https://modelcontextprotocol.io/llms-full.txt

This comprehensive document contains the complete MCP specification and guidelines.

1.4 Study Framework Documentation

Load and read the following reference files:

MCP Best Practices: 📋 View Best Practices - Core guidelines for all MCP servers

For Python implementations, also load:

Python SDK Documentation: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

🐍 Python Implementation Guide - Python-specific best practices and examples

For Node/TypeScript implementations, also load:

TypeScript SDK Documentation: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

⚡ TypeScript Implementation Guide - Node/TypeScript-specific best practices and examples

1.5 Exhaustively Study API Documentation

To integrate a service, read through ALL available API documentation:

Official API reference documentation

Authentication and authorization requirements

Rate limiting and pagination patterns

Error responses and status codes

Available endpoints and their parameters

Data models and schemas

To gather comprehensive information, use web search and the WebFetch tool as needed.

1.6 Create a Comprehensive Implementation Plan

Based on your research, create a detailed plan that includes:

Tool Selection:

List the most valuable endpoints/operations to implement

Prioritize tools that enable the most common and important use cases

Consider which tools work together to enable complex workflows

Shared Utilities and Helpers:

Identify common API request patterns

Plan pagination helpers

Design filtering and formatting utilities

Plan error handling strategies

Input/Output Design:

Define input validation models (Pydantic for Python, Zod for TypeScript)

Design consistent response formats (e.g., JSON or Markdown), and configurable levels of detail (e.g., Detailed or Concise)

Plan for large-scale usage (thousands of users/resources)

Implement character limits and truncation strategies (e.g., 25,000 tokens)

Error Handling Strategy:

Plan graceful failure modes

Design clear, actionable, LLM-friendly, natural language error messages which prompt further action

Consider rate limiting and timeout scenarios

Handle authentication and authorization errors

Phase 2: Implementation

Now that you have a comprehensive plan, begin implementation following language-specific best practices.

2.1 Set Up Project Structure

For Python:

Create a single .py file or organize into modules if complex (see 🐍 Python Guide)

Use the MCP Python SDK for tool registration

Define Pydantic models for input validation

For Node/TypeScript:

Create proper project structure (see ⚡ TypeScript Guide)

Set up package.json and tsconfig.json

Use MCP TypeScript SDK

Define Zod schemas for input validation

2.2 Implement Core Infrastructure First

To begin implementation, create shared utilities before implementing tools:

API request helper functions

Error handling utilities

Response formatting functions (JSON and Markdown)

Pagination helpers

Authentication/token management

2.3 Implement Tools Systematically

For each tool in the plan:

Define Input Schema:

Use Pydantic (Python) or Zod (TypeScript) for validation

Include proper constraints (min/max length, regex patterns, min/max values, ranges)

Provide clear, descriptive field descriptions

Include diverse examples in field descriptions

Write Comprehensive Docstrings/Descriptions:

One-line summary of what the tool does

Detailed explanation of purpose and functionality

Explicit parameter types with examples

Complete return type schema

Usage examples (when to use, when not to use)

Error handling documentation, which outlines how to proceed given specific errors

Implement Tool Logic:

Use shared utilities to avoid code duplication

Follow async/await patterns for all I/O

Implement proper error handling

Support multiple response formats (JSON and Markdown)

Respect pagination parameters

Check character limits and truncate appropriately

Add Tool Annotations:

readOnlyHint: true (for read-only operations)

destructiveHint: false (for non-destructive operations)

idempotentHint: true (if repeated calls have same effect)

openWorldHint: true (if interacting with external systems)

2.4 Follow Language-Specific Best Practices

At this point, load the appropriate language guide:

For Python: Load 🐍 Python Implementation Guide and ensure the following:

Using MCP Python SDK with proper tool registration

Pydantic v2 models with model_config

Type hints throughout

Async/await for all I/O operations

Proper imports organization

Module-level constants (CHARACTER_LIMIT, API_BASE_URL)

For Node/TypeScript: Load ⚡ TypeScript Implementation Guide and ensure the following:

Using server.registerTool properly

Zod schemas with .strict()

TypeScript strict mode enabled

No any types - use proper types

Explicit Promise return types

Build process configured (npm run build)

Phase 3: Review and Refine

After initial implementation:

3.1 Code Quality Review

To ensure quality, review the code for:

DRY Principle: No duplicated code between tools

Composability: Shared logic extracted into functions

Consistency: Similar operations return similar formats

Error Handling: All external calls have error handling

Type Safety: Full type coverage (Python type hints, TypeScript types)

Documentation: Every tool has comprehensive docstrings/descriptions

3.2 Test and Build

Important: MCP servers are long-running processes that wait for requests over stdio/stdin or sse/http. Running them directly in your main process (e.g., python server.py or node dist/index.js) will cause your process to hang indefinitely.

Safe ways to test the server:

Use the evaluation harness (see Phase 4) - recommended approach

Run the server in tmux to keep it outside your main process

Use a timeout when testing: timeout 5s python server.py

For Python:

Verify Python syntax: python -m py_compile your_server.py

Check imports work correctly by reviewing the file

To manually test: Run server in tmux, then test with evaluation harness in main process

Or use the evaluation harness directly (it manages the server for stdio transport)

For Node/TypeScript:

Run npm run build and ensure it completes without errors

Verify dist/index.js is created

To manually test: Run server in tmux, then test with evaluation harness in main process

Or use the evaluation harness directly (it manages the server for stdio transport)

3.3 Use Quality Checklist

To verify implementation quality, load the appropriate checklist from the language-specific guide:

Python: see "Quality Checklist" in 🐍 Python Guide

Node/TypeScript: see "Quality Checklist" in ⚡ TypeScript Guide

Phase 4: Create Evaluations

After implementing your MCP server, create comprehensive evaluations to test its effectiveness.

Load ✅ Evaluation Guide for complete evaluation guidelines.

4.1 Understand Evaluation Purpose

Evaluations test whether LLMs can effectively use your MCP server to answer realistic, complex questions.

4.2 Create 10 Evaluation Questions

To create effective evaluations, follow the process outlined in the evaluation guide:

Tool Inspection: List available tools and understand their capabilities

Content Exploration: Use READ-ONLY operations to explore available data

Question Generation: Create 10 complex, realistic questions

Answer Verification: Solve each question yourself to verify answers

4.3 Evaluation Requirements

Each question must be:

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>

Reference Files

📚 Documentation Library

Load these resources as needed during development:

Core MCP Documentation (Load First)

MCP Protocol: Fetch from https://modelcontextprotocol.io/llms-full.txt - Complete MCP specification

📋 MCP Best Practices - Universal MCP guidelines including:

Server and tool naming conventions

Response format guidelines (JSON vs Markdown)

Pagination best practices

Character limits and truncation strategies

Tool development guidelines

Security and error handling standards

SDK Documentation (Load During Phase 1/2)

Python SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

TypeScript SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Language-Specific Implementation Guides (Load During Phase 2)

🐍 Python Implementation Guide - Complete Python/FastMCP guide with:

Server initialization patterns

Pydantic model examples

Tool registration with @mcp.tool

Complete working examples

Quality checklist

⚡ TypeScript Implementation Guide - Complete TypeScript guide with:

Project structure

Zod schema patterns

Tool registration with server.registerTool

Complete working examples

Quality checklist

Evaluation Guide (Load During Phase 4)

✅ Evaluation Guide - Complete evaluation creation guide with:

Question creation guidelines

Answer verification strategies

XML format specifications

Example questions and answers

Running an evaluation with the provided scripts

don't have the plugin yet? install it then click "run inline in claude" again.

restructured raw content into implexa's 6-component format, added explicit decision points for deployment paths and error handling, clarified external connections with env var names, added edge cases for retry backoff and async initialization, preserved all original steps and patterns faithfully.

intent

build a production-ready mcp server from a written description of tools, resources, and prompts you need to expose. use this skill when you want to scaffold a python fastmcp server, test it locally, and deploy to fastmcp cloud or self-hosted environments. the skill covers the full lifecycle from design through deployment checklist, with patterns for auth, error handling, and common edge cases.

inputs

required context:

description of what the server needs to expose (tools, resources, prompts)
python 3.12+ environment with pip available
git repository initialized (for cloud deployment)

external connections:

fastmcp library (pypi): pip install fastmcp
fastmcp cloud (optional): github oauth, public repo, env var secrets via dashboard
docker (optional): for self-hosted deployment
cloudflare workers (optional): see cloudflare-worker-builder skill

environment variables (cloud deployment):

API_KEY, DB_URL, BASE_URL, etc.: set in fastmcp cloud dashboard, never hardcoded
FASTMCP_LOG_LEVEL: DEBUG/INFO/WARNING/ERROR (optional, defaults to INFO)
FASTMCP_ENV: development/staging/production (optional)

procedure

step 1: define what to expose

input: written brief describing server purpose

list tools (functions claude can call): api wrappers, calculations, file operations
list resources (data claude can read): database records, config, documents
list prompts (reusable templates with parameters): optional
example: "mcp server for querying our customer database, exporting reports, checking health"

output: clear specification of 3-5 tools/resources needed

step 2: scaffold the server

input: specification from step 1, python 3.12+

install fastmcp: pip install fastmcp
create server file (e.g., server.py) with module-level server instance:

from fastmcp import FastMCP
import os

mcp = FastMCP("My Server")  # MUST be at module level

@mcp.tool()
async def search_customers(query: str) -> str:
    """Search customers by name or email."""
    return f"Found customers matching: {query}"

@mcp.resource("customers://{customer_id}")
async def get_customer(customer_id: str) -> str:
    """Get customer details by ID."""
    return f"Customer {customer_id} details"

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

output: server.py with all tools, resources, prompts defined; requirements.txt with fastmcp and dependencies listed

critical constraint: server instance (mcp, server, or app) must be at module level, not inside a function, or fastmcp cloud cannot find it

step 3: add companion cli scripts (optional)

input: server.py from step 2, use case requiring file i/o or batch processing

create scripts/ folder alongside server
write typescript cli scripts for batch operations, file i/o, richer output than mcp
reference assets/script-template.ts and assets/SCRIPTS-TEMPLATE.md

output: scripts/ folder with _shared.ts (auth/config), individual cli scripts, SCRIPTS.md documenting them

step 4: test locally

input: server.py from step 2, optional cli scripts from step 3

test method (pick one):

a) quick test (direct run):

command: python server.py
output: server starts on stdio transport

b) dev mode with inspector ui (recommended):

command: fastmcp dev server.py
output: hot reload enabled, inspector ui opens at http://localhost:5173, detailed logging visible
action: test tools/resources via inspector ui

c) http mode (remote clients):

command: python server.py --transport http --port 8000
output: server listens on http://localhost:8000

d) automated test script:

create test script using fastmcp client:

import asyncio
from fastmcp import Client

async def test_server(server_path):
    async with Client(server_path) as client:
        tools = await client.list_tools()
        resources = await client.list_resources()
        prompts = await client.list_prompts()
        
        print(f"Tools: {[t.name for t in tools]}")
        print(f"Resources: {[r.uri for r in resources]}")
        print(f"Prompts: {[p.name for p in prompts]}")
        
        if tools:
            result = await client.call_tool(tools[0].name, {})
            print(f"Tool result: {result}")
        
        if resources:
            data = await client.read_resource(resources[0].uri)
            print(f"Resource data: {data}")

asyncio.run(test_server("server.py"))

command: python test_script.py
output: list of tools/resources, sample tool call result, sample resource read

output: verified server behavior, no errors logged

step 5: pre-deploy checklist

input: server.py, requirements.txt, optional cli scripts

run all checks (some required, some advisory):

required (fail deployment if missing):

server file exists: test -f server.py
python syntax valid: python3 -m py_compile server.py
module-level server object: grep -q "^mcp = FastMCP\|^server = FastMCP\|^app = FastMCP" server.py
requirements.txt exists with pypi packages only (no git+, -e, .whl, .tar.gz)
no hardcoded secrets: grep -i "api_key\s*=\s*['\"]" server.py should return zero matches (os.getenv/os.environ calls are ok)
server loads without error: timeout 5 fastmcp inspect server.py

advisory (warnings):

fastmcp listed in requirements.txt
.gitignore includes .env
no circular imports (test: python -c "import server")
git repository initialized with remote: git remote -v

output: checklist pass/fail results; all required checks must pass before deployment

step 6: deploy

input: checked server.py, requirements.txt, git repo from step 5

deployment option (pick one):

a) fastmcp cloud (simplest):

commit and push: git add . && git commit -m "Ready for deployment" && git push -u origin main
action: visit https://fastmcp.cloud
action: connect github repo, add environment variables (API_KEY, etc.)
action: deploy
output: https://your-project.fastmcp.app/mcp endpoint live, auto-deploys on push to main, pr previews enabled
cloud requirements: module-level server object named mcp/server/app, pypi dependencies only, public github repo, no hardcoded secrets

b) docker (self-hosted):

create dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py", "--transport", "http", "--port", "8000"]

build: docker build -t my-mcp-server .
run: docker run -e API_KEY=xxx -p 8000:8000 my-mcp-server
output: container listening on http://localhost:8000

c) cloudflare workers (edge):

see cloudflare-worker-builder skill for workers-based approach

output: deployed endpoint url (cloud or self-hosted), verified working via client connection

decision points

if the server needs to call external apis (salesforce, hubspot, stripe, etc.):

use os.getenv("API_KEY") to load secrets from environment, never hardcode
use httpx.AsyncClient with connection pooling and retry backoff for reliability
return error strings instead of raising exceptions

if deploying to fastmcp cloud:

ensure module-level server instance named mcp, server, or app
requirements.txt must contain only pypi packages (no git+, -e, .whl, .tar.gz)
set all secrets via fastmcp cloud dashboard env vars
use public github repository
else, fall back to docker or cloudflare workers for self-hosted/edge deployment

if the server has async resource initialization (database connections, etc.):

use lazy initialization pattern (check if _db is None on first call, then create)
do not create async resources at module level (causes import-time execution errors)

if tools need to report progress or request llm sampling from within execution:

add context: Context parameter with type hint
use await context.report_progress(current, total, message) for progress
use await context.request_sampling(...) for llm calls inside tools

if the server performs long-running or flaky operations:

implement retry_with_backoff helper for transient failures
set connection pool limits and timeouts via httpx.AsyncClient
add health check resource at health://status for monitoring

if tests fail with "RuntimeError: No server object found at module level":

move server instance from inside a function to module level
if using factory pattern, assign result to module-level variable: mcp = create_server()

if tests fail with "RuntimeError: no running event loop":

ensure all async functions use async def and are awaited
use async context managers (async with) for client connections

if the server needs to list tools, resources, or prompts dynamically at runtime:

use @mcp.tool() / @mcp.resource() / @mcp.prompt() decorators
fastmcp introspects decorated functions at startup

if deploy fails with "Port already in use":

kill stale process: lsof -ti:8000 | xargs kill -9
or specify different port: --port 8001

if deploy fails with "JSON serialization error":

ensure tool/resource responses use json-compatible types (str, dict, list, int, float, bool, null)
convert datetime to .isoformat(), bytes to base64 or hex string
avoid numpy arrays, custom objects without dict

output contract

successful server deployment produces:

file structure:

server.py: python fastmcp server with module-level instance, all tools/resources/prompts decorated
requirements.txt: pypi dependencies (fastmcp, httpx, etc.)
.env.example: template for environment variables (secrets not included)
optional: scripts/ folder with cli companions
optional: dockerfile for self-hosted deployment
optional: SCRIPTS.md documenting cli usage

code quality:

python 3.12+ syntax valid
all functions type-hinted (required for schema generation)
all tools return strings or json-serializable dicts, not exceptions
all resources use valid uri schemes (data://, file://, info://, api://, custom://)
module-level server instance named mcp, server, or app

deployment:

fastmcp cloud: live endpoint at https://your-project.fastmcp.app/mcp
docker: container image pushed, running on specified port
cloudflare workers: deployed to edge locations

monitoring:

health://status resource available returning {"status": "healthy", "version": "...", "checks": {...}}
logs visible in fastmcp cloud dashboard or container logs
environment variables set and verified in dashboard or container startup

outcome signal

the skill worked when:

fastmcp dev server.py opens inspector ui with zero errors, shows all tools/resources/prompts listed
calling a tool via inspector returns expected output (string or json), not an exception
reading a resource via inspector returns expected data
git push to main triggers auto-deployment in fastmcp cloud (check deploy status in dashboard)
client connects to deployed endpoint and receives list_tools, list_resources responses
health://status resource returns {"status": "healthy", ...}
calling tools with missing environment variables returns {"error": "API_KEY not configured"} or similar, not a crash
docker container builds and runs without errors, listens on specified port
all pre-deploy checks pass (syntax, module-level instance, no hardcoded secrets, loads within 5 seconds)
team can use the server in claude.ai or claude desktop, calling tools and reading resources without manual setup steps