Build an MCP Server from Scratch
A Complete Developer Guide

Why AI Needs an MCP Server: An LLM Without Tools Is Just a Talking Brain

Large models have training cutoffs and cannot reach your CRM, Git repos, or internal APIs. Before 2024, you wrote Function Calling for Claude, Plugins for GPT, and a different format for Cursor — switch models, start over. An MCP Server wraps tool capabilities in an independent process: write once, use across Claude Desktop, Cursor, and Gemini.

Typical scenarios: query Postgres sales data from Claude Desktop; have a Cursor Agent read project docs and edit code; call your ticketing system over HTTP MCP from GPT — all backed by the same Server.

What this guide delivers: not theory alone, but a path from say_hello to a production-grade knowledge-base Server with vector search. Target reader: developers with Python or TypeScript basics who want to extend AI in their IDE or Desktop app.

Six Pain Points: Why Wrapping APIs Is Not Enough

1. 01

   Vendor lock-in: OpenAI Function Calling and Claude Tool Use use different formats — every vendor switch means rewriting the adapter layer.

2. 02

   Tools cannot be discovered: REST APIs rely on static docs; AI cannot call tools/list at runtime to discover capabilities on its own.

3. 03

   IDE silos: Cursor, VS Code extensions, and JetBrains plugins each define tools differently — you maintain N×M integrations.

4. 04

   Context and data split: LLMs cannot reliably read config files, user preferences, or live logs — you need standardized read-only Resources.

5. 05

   Scattered prompt templates: code review and incident report templates have no unified registry; teams copy-paste independently.

6. 06

   Local vs remote deployment chaos: stdio subprocesses suit development, but production HTTP gateways, auth, and monitoring lack a shared pattern (see our stdio subprocess management guide).

Dev Environment Setup: Python FastMCP vs TypeScript SDK

Two main paths: Python mcp + FastMCP (data/script friendly) and TypeScript @modelcontextprotocol/sdk (Web/API integration, type safety). SDK repos: python-sdk, typescript-sdk.

# Python 路线
python -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic

# TypeScript 路线
npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

Recommended Project Structure

my-mcp-server/
├── pyproject.toml          # 或 package.json
├── src/
│   ├── server.py           # FastMCP 入口
│   ├── tools/              # 各工具模块
│   ├── resources/          # Resource 提供者
│   └── prompts/            # Prompt 模板
├── tests/
│   └── test_tools.py       # pytest + ClientSession
├── Dockerfile
└── README.md

Six-Step Environment Readiness Checklist

1. 01

   Pick a stack: data/ML teams prefer Python; Node full-stack teams prefer TypeScript.

2. 02

   Create a virtual env and lock dependencies: pip freeze or package-lock.json to prevent schema drift.

3. 03

   Install MCP Inspector: npx @modelcontextprotocol/inspector for visual JSON-RPC debugging.

4. 04

   Configure Claude Desktop: edit ~/Library/Application Support/Claude/claude_desktop_config.json and add Server command/args.

5. 05

   Configure Cursor: Settings → MCP → Add Server; for stdio use python -m src.server or an absolute path.

6. 06

   Verify Inspector connectivity: start Server → connect Inspector → confirm tools/list returns a non-empty list.

// Cursor / Claude Desktop MCP 配置示例
{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

Tools Deep Dive: From Schema to Five Production-Grade Tools

Tools are MCP's core capability: AI executes side-effect operations via tools/call. Each Tool exposes a name, description, and inputSchema; FastMCP uses Pydantic models for validation.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="搜索关键词")
    limit: int = Field(10, ge=1, le=100, description="返回条数")

@mcp.tool()
async def search_docs(params: SearchInput) -> str:
    """在文档库中搜索"""
    results = await index.search(params.query, params.limit)
    return json.dumps(results, ensure_ascii=False)

Five Common Tool Patterns

• calculator: safe eval or ast.literal_eval; never exec.
• file_read / file_write: restrict to a root directory whitelist to prevent path traversal.
• fetch_url (async): use httpx with timeout and domain whitelist.
• db_query: read-only SQL with parameterized queries; no DDL.
• get_current_time: return ISO8601 timezone-aware time to fix LLM time hallucination.

import httpx
from datetime import datetime, timezone

@mcp.tool()
async def fetch_url(url: str) -> str:
    """HTTP GET 获取 URL 内容（域名白名单内）"""
    allowed = ("api.github.com", "nodemini.com")
    if not any(url.startswith(f"https://{d}") for d in allowed):
        raise ValueError(f"Domain not allowed: {url}")
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:8000]

@mcp.tool()
def get_current_time() -> str:
    """返回当前 UTC 时间"""
    return datetime.now(timezone.utc).isoformat()

Error Handling Best Practices

• Return structured errors: use raise ValueError("human-readable msg"); the Client passes the message back to the LLM.
• Separate retryable vs fatal: mark network timeouts as retryable; fail fast on permission denied.
• Log and redact: log tool name and latency; never log full API keys or PII.
• Design for idempotency: write operations carry an idempotency_key to prevent duplicate Agent calls from corrupting data.

Prompts: Reusable Multi-Turn Conversation Templates

An MCP Prompt is a conversation skeleton registered on the Server. The Client fetches a message list via prompts/get, with user / assistant roles and parameter placeholders — teams share code review and incident workflows without maintaining per-user prompt files.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str = "python") -> list[PromptMessage]:
    """标准化 Code Review 多轮模板"""
    return [
        PromptMessage(role="user", content=TextContent(
            type="text",
            text=f"你是资深 {language} 工程师。请按安全、性能、可读性三维审查以下 diff。"
        )),
        PromptMessage(role="assistant", content=TextContent(
            type="text",
            text="请粘贴 diff 或指定 PR 编号，我将按 CHECKLIST 输出结构化 review。"
        )),
    ]

Multi-turn templates can nest variables ({ticket_id}, {severity}). The Server owns version management; when the Client upgrades the Server, the whole team gets the latest review standards.

Debugging and Testing: Inspector + pytest Unit Tests

MCP Inspector is the official visual debugger: connect via stdio or URL, manually send tools/list and tools/call, inspect JSON-RPC round trips — far faster than guessing from Cursor logs.

# tests/test_tools.py
import pytest
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

@pytest.mark.asyncio
async def test_say_hello():
    params = StdioServerParameters(command="python", args=["-m", "src.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("say_hello", {"name": "MCP"})
            assert "MCP" in result.content[0].text

Common Error Reference

Hands-On Project: ChromaDB Knowledge Base MCP Server

Vectorize internal Wiki / Markdown docs and expose index_document, search_knowledge, and write_note tools so a Cursor Agent can "search the company knowledge base before writing code."

Requirements: incremental indexing (watchfiles on docs/), semantic search Top-K, optional scratchpad writes.

import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

client = chromadb.PersistentClient(path="./data/chroma")
collection = client.get_or_create_collection(
    "wiki", embedding_function=SentenceTransformerEmbeddingFunction()
)

@mcp.tool()
def search_knowledge(query: str, top_k: int = 5) -> str:
    """语义搜索内部知识库"""
    hits = collection.query(query_texts=[query], n_results=top_k)
    return json.dumps(hits["documents"][0], ensure_ascii=False)

@mcp.tool()
def index_document(path: str) -> str:
    """索引单个 Markdown 文件"""
    text = open(path).read()
    collection.upsert(ids=[path], documents=[text], metadatas=[{"path": path}])
    return f"Indexed: {path}"

Cursor demo query: "Search the knowledge base for MCP HTTP deployment docs, then summarize a three-step launch checklist" — the Agent calls search_knowledge first, then answers from retrieved context. Swap the vector store for Qdrant (remote gRPC) at larger scale.