Build an MCP Server from Scratch:
A Complete Developer Guide

Pain points: Every LLM vendor ships a different function-calling format. Switch models and you rewrite integrations. LangChain tools stay inside the framework and do not travel across IDEs.

• Evolution: Function Calling (vendor-specific) → ChatGPT Plugins (platform lock-in) → MCP (open standard). Anthropic open-sourced MCP in November 2024 to unify AI-to-system communication via JSON-RPC.
• Roles: The MCP Client lives on the AI side (Claude Desktop, Cursor). The MCP Server is what you build. It exposes Tools (callable functions), Resources (readable data), and Prompts (reusable templates).
• Transport: JSON-RPC 2.0 over stdio (local, low latency) or HTTP + SSE / Streamable HTTP (remote, multi-client). Lifecycle: handshake → capability negotiation → requests → shutdown.

Write one MCP Server—Cursor, Claude Desktop, and VS Code can all call it. That is the USB-C moment for AI tooling.

Language choice: Python with the official mcp package and FastMCP (best for beginners). TypeScript with @modelcontextprotocol/sdk for full-stack teams. Examples below use Python.

python -m venv .venv
source .venv/bin/activate
pip install mcp

npm init -y
npm install @modelcontextprotocol/sdk

Project layout: server.py, tools/, resources/, prompts/, tests/, pyproject.toml.

Debug stack: Official MCP Inspector (npx @modelcontextprotocol/inspector), Claude Desktop via claude_desktop_config.json, Cursor via Settings → MCP.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}! This is your first MCP tool."

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

Run python server.py or npx @modelcontextprotocol/inspector python server.py. After configuring Cursor or Claude Desktop, the tool should appear in the AI context.

Function signatures become JSON Schema for the model. Use snake_case verb names like search_web. Complex inputs map cleanly through Pydantic BaseModel with Field(description=...).

Five starter tools: calculator (safe expression parsing), file read/write (directory allowlist), HTTP client (timeouts and size caps), read-only SQL (parameterized queries), and timezone utilities.

Async IO: Use async def with httpx.AsyncClient for network calls. Return structured error dicts instead of raw exceptions. Add timeouts and permission checks for production paths.

Resource vs Tool: Resources provide data; Tools perform actions. Address resources by URI: file://, http://, custom://. Static resources use fixed URIs; dynamic ones accept parameters like user://{user_id}/profile.

Support text, JSON, binary, and streaming payloads. A filesystem resource server can list directories, read files, and subscribe to change events.

Prompts ship pre-built message templates with injected parameters—ideal for code review, interview simulation, or debug assistants. Multi-turn templates can mix user and assistant roles.

Remote example: FastMCP("remote-server", transport="streamable-http") behind uvicorn on port 8000. Harden with Bearer tokens, API-key middleware, CORS allowlists, and rate limits.

Test with MCP Inspector and pytest via mcp.client.stdio. Common failures: wrong config path (tool invisible), non-serializable return types, and blocking calls causing timeouts.

Ship with Docker (Python 3.12-slim), Railway/Render for hobby projects, Lambda/Cloud Run for serverless, or Nginx on a VPS. Add structured logs, Prometheus metrics, Sentry alerts, and a /health endpoint. Declare MCP protocol versions and keep tool upgrades backward compatible.

Capstone: A personal knowledge-base MCP Server that semantic-searches Markdown notes, creates entries, and watches files with ChromaDB/Qdrant, text-embedding-3-small, and watchfiles. Ask Cursor: "What did I write about MCP last week?" and the agent calls your search tool.

2026 reference servers: mcp-server-filesystem, mcp-server-github, mcp-server-brave-search, mcp-server-postgres, mcp-server-slack. Major clients now ship native MCP support; enterprise security baselines and marketplaces are maturing.

• Protocol: Anthropic open-sourced MCP in November 2024 (JSON-RPC 2.0); governance moved to Linux Foundation AAIF in 2026.
• Ecosystem: Public MCP servers exceed 10,000; Python and TypeScript SDKs are the official maintenance path—verify versions on GitHub after release.
• Transport: Streamable HTTP is replacing pure SSE for stateless load balancing in cloud deployments.

Official docs and SDKs (re-check links after upstream releases):

https://modelcontextprotocol.io

https://github.com/modelcontextprotocol/python-sdk

https://github.com/modelcontextprotocol/typescript-sdk

https://github.com/modelcontextprotocol/inspector

1. Pick language and transport: Python + stdio for solo dev; HTTP for team sharing.
2. Scaffold modules: Split tools, resources, prompts; install MCP Inspector.
3. Ship Hello World: Verify visibility in Cursor or Claude Desktop.
4. Add five tools plus resources: Start read-only, then writes and external APIs.
5. Automate tests and Docker: Run stdio integration tests in CI.
6. Deploy 24/7: Laptop sleep kills MCP sessions; plain Linux VPS lacks macOS sandboxes and Xcode. For stable MCP infra, shared agents, and iOS CI, CALMVPS bare-metal Mac rental is usually the better fit: dedicated M4/M4 Pro, ~120s provisioning, flexible billing. See pricing and help center.

MCP is the standard protocol for AI tooling. Master it and you can extend any LLM with real-world capabilities—starting with today's Hello World.