MCP Server Builder

MCP Server Builder

What this skill does

This skill walks you through building a Model Context Protocol (MCP) server from scratch. MCP servers expose tools, resources, and prompts to AI agents (Claude, Cursor, Cline, etc.). This skill covers both Python (FastMCP) and TypeScript (official SDK) implementations, with production-ready patterns for error handling, input validation, and tool description writing.

How to use

Claude Code / Cline

Copy this file to .agents/skills/mcp-server-builder/SKILL.md in your project root.

Then ask:

• "Use the MCP Server Builder to create a server that exposes our internal database as tools."
• "Build an MCP server in Python that wraps our REST API."

Provide:

• What capabilities you want to expose (tools, resources, or both)
• Language preference (Python or TypeScript)
• Whether it will run locally (stdio) or as a remote server (HTTP)
• What systems it needs to connect to

Cursor / Codex

Describe the tools you want to expose alongside these instructions.

The Prompt / Instructions for the Agent

When asked to build an MCP server, produce the following:

Step 1 — Choose transport

Use case	Transport
Local tool for one developer	stdio (local process)
Team-shared server	Streamable HTTP (remote)
Claude Desktop integration	stdio
Multi-user / production	HTTP with auth

Step 2a — Python implementation (FastMCP)

# Install: pip install fastmcp
from fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("my-server")

# --- Tool definition ---
class SearchInput(BaseModel):
    query: str = Field(description="The search query to run")
    limit: int = Field(default=10, ge=1, le=50, description="Max results to return")

@mcp.tool()
async def search_documents(input: SearchInput) -> str:
    """
    Search the document database for relevant content.

    Use this when the user asks to find, look up, or search for documents.
    Returns a formatted list of matching documents with titles and summaries.
    """
    try:
        results = await db.search(input.query, limit=input.limit)
        if not results:
            return "No documents found matching your query."
        return "\n".join(f"- {r.title}: {r.summary}" for r in results)
    except Exception as e:
        return f"Error searching documents: {str(e)}"

# --- Resource definition (read-only data) ---
@mcp.resource("config://app-settings")
async def get_app_settings() -> str:
    """Returns the current application configuration."""
    return json.dumps(load_config(), indent=2)

# Run with stdio (for local / Claude Desktop)
if __name__ == "__main__":
    mcp.run()

# Run with HTTP (for remote / team use)
# mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)