Build an MCP Server from Scratch:
A Complete Developer Guide

LLMs are strong reasoners but weak executors. The first fix was OpenAI Function Calling (June 2023): define JSON schemas, let the model emit structured calls, your code executes them. It worked—but only inside OpenAI's API. Every other model needed a separate adapter.

ChatGPT Plugins (March 2023) tried a marketplace model: each plugin was a bespoke REST wrapper with its own manifest. Discovery was centralized in OpenAI's store, not runtime-dynamic. When Anthropic shipped Tool Use and LangChain popularized agent frameworks, the industry had three incompatible tool schemas and no portable server layer.

Anthropic's design rationale mirrors USB-C: standardize the port, not every cable. MCP does not replace REST APIs—it wraps them behind a uniform discovery and invocation layer so AI clients stop caring which vendor or framework sits on the other side. By Q2 2026 governance moved to the Linux Foundation AAIF; OpenAI, Google, and Microsoft all ship native MCP client support.

MCP runs on JSON-RPC 2.0 with bidirectional messaging. A Host (Cursor, Claude Desktop) embeds one or more MCP Clients. Each Client maintains a 1:1 session with an MCP Server that bridges to real systems.

Servers expose three capability types: Tools (executable actions with side effects), Resources (read-only data identified by URIs), and Prompts (reusable template strings the client can pre-fill). Core RPC methods include tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": { "sql": "SELECT id, email FROM users LIMIT 10" }
  },
  "id": 42
}

STDIO transport: Host spawns Server as a subprocess; messages flow over stdin/stdout. Zero network deps, strong process isolation, ideal for local dev. Lifecycle: spawn → initialize handshake → capability negotiation → persistent session → subprocess exit on disconnect.

HTTP + SSE / streamable-http: Server runs as a long-lived HTTP service. Client opens SSE stream for server-push events; tool calls go via POST. Enables remote deploy, team-shared servers, horizontal scaling—but requires session affinity for SSE and proper auth at the edge. The 2026 spec adds streamable-http as the recommended remote transport, replacing legacy SSE-only patterns.

Pick your SDK stack: Python with mcp + FastMCP for fastest iteration, or TypeScript with @modelcontextprotocol/sdk for Node-native HTTP servers. Recommended project layout:

my-mcp-server/
  pyproject.toml
  src/
    server.py          # FastMCP entry
    tools/             # tool modules
    resources/         # resource handlers
    prompts/           # prompt templates
  tests/
    test_tools.py
  Dockerfile

Install: pip install mcp or npm install @modelcontextprotocol/sdk. Debug with MCP Inspector (npx @modelcontextprotocol/inspector)—connects to STDIO or HTTP endpoints and shows live tools/list output. Wire into Cursor via Settings → MCP → add server config; Claude Desktop via claude_desktop_config.json.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-mcp")

@mcp.tool()
def greet(name: str) -> str:
    return f"Hello, {name}!"

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

Tools with Pydantic input: FastMCP derives JSON Schema from type hints and Pydantic models automatically. Below: five practical tools—calculator, file I/O, HTTP fetch, DB query, and time—with async support and structured error returns.

import asyncio
import httpx
from datetime import datetime, timezone
from pathlib import Path
from pydantic import BaseModel, Field
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("utility-server")

class CalcInput(BaseModel):
    expression: str = Field(description="Math expression e.g. 2 + 3 * 4")

@mcp.tool()
def calculate(input: CalcInput) -> str:
    try:
        allowed = set("0123456789+-*/(). ")
        if not all(c in allowed for c in input.expression):
            return "Error: invalid characters in expression"
        return str(eval(input.expression, {"__builtins__": {}}, {}))
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
def read_file(path: str) -> str:
    try:
        target = Path(path).resolve()
        if not target.is_file():
            return f"Error: {path} is not a file"
        return target.read_text(encoding="utf-8", errors="replace")[:50000]
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
async def http_get(url: str) -> str:
    try:
        async with httpx.AsyncClient(timeout=15.0) as client:
            resp = await client.get(url)
            return resp.text[:10000]
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
async def db_query(sql: str) -> str:
  try:
    import aiosqlite
    async with aiosqlite.connect("app.db") as db:
      cursor = await db.execute(sql)
      rows = await cursor.fetchall()
      return str(rows[:100])
  except Exception as e:
    return f"Error: {e}"

@mcp.tool()
def current_time(tz: str = "UTC") -> str:
    return datetime.now(timezone.utc).isoformat()

Resources: Static URIs map to fixed files; dynamic URIs accept parameters. A filesystem resource server exposes project docs the agent can read without tool side effects.

from mcp.server.fastmcp import FastMCP
from pathlib import Path

mcp = FastMCP("fs-resources")
DOCS = Path("./docs")

@mcp.resource("docs://index")
def docs_index() -> str:
    files = [f.name for f in DOCS.glob("*.md")]
    return "\n".join(files)

@mcp.resource("docs://{filename}")
def read_doc(filename: str) -> str:
    path = DOCS / filename
    if not path.exists():
        return f"Error: {filename} not found"
    return path.read_text(encoding="utf-8")

Prompts: Reusable templates with argument slots. A code-review prompt pre-fills context so the agent follows your team's review checklist.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("review-prompts")

@mcp.prompt()
def code_review(file_path: str, language: str) -> str:
    return f"""Review {file_path} ({language}) for:
1. Security vulnerabilities (injection, auth bypass)
2. Performance bottlenecks
3. Error handling gaps
4. Test coverage holes
Provide severity-rated findings with fix suggestions."""

Streamable HTTP transport is the 2026 default for remote MCP Servers. Run FastMCP with mcp.run(transport="streamable-http") or use the TypeScript SDK's StreamableHTTPServerTransport. Layer security at the edge:

Debugging workflow: MCP Inspector first, then client logs, then unit tests. Inspector shows raw JSON-RPC, schema validation errors, and timing per call.

import pytest
from server import calculate, CalcInput

def test_calculate_valid():
    result = calculate(CalcInput(expression="2 + 3"))
    assert result == "5"

def test_calculate_invalid_chars():
    result = calculate(CalcInput(expression="import os"))
    assert result.startswith("Error:")

Six-step runbook from assessment to production-ready MCP Server:

Production paths: Package with Docker (python:3.12-slim base, non-root user, health check on HTTP port). Platform options:

Monitoring: Export request latency and tool-call counters to Prometheus; ship exceptions to Sentry with MCP method name tags. Pin SDK versions in pyproject.toml / package.json and tag Docker images per release—MCP spec revisions in 2026 still ship breaking transport changes.

Capstone: personal knowledge base MCP. Combine ChromaDB vector store, embedding model (local Ollama or API), and semantic search tool:

import chromadb
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("knowledge-base")
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_or_create_collection("notes")

@mcp.tool()
def semantic_search(query: str, n: int = 5) -> str:
    results = collection.query(query_texts=[query], n_results=n)
    docs = results.get("documents", [[]])[0]
    return "\n---\n".join(docs) if docs else "No matches found."

@mcp.tool()
def ingest_note(text: str, source: str) -> str:
    collection.add(documents=[text], metadatas=[{"source": source}], ids=[source])
    return f"Indexed: {source}"

2026 ecosystem servers to study: mcp-server-filesystem (official reference), GitHub MCP (repo/PR/issue ops), Brave Search MCP (web retrieval), Postgres MCP (SQL with schema introspection), Slack MCP (channel messaging). Trends for H2 2026: OAuth 2.1 standardized auth, unified server registries, multi-tenant hosted MCP marketplaces, and Agent-to-Agent (A2A) orchestration sitting above MCP's tool layer.

For teams running MCP Servers alongside Cursor agents, ChromaDB ingestion, and iOS CI on one always-on node, MESHLAUNCH cloud Mac Mini rental is usually the better production host: dedicated Apple Silicon, no sleep disconnects, flexible daily/weekly/monthly billing, and a stable home where tool definitions become portable team assets instead of per-developer laptop configs. See pricing for node specs.