MCP Server von Grund auf entwickeln
Vollständiger Entwicklerleitfaden

Warum KI einen MCP Server braucht: Ein LLM ohne Tools ist nur ein redendes Gehirn

Große Modelle haben Trainings-Stichtage und erreichen Ihr CRM, Git-Repository oder interne APIs nicht. Vor 2024 schrieben Sie Function Calling für Claude, Plugins für GPT und ein anderes Format für Cursor — Modellwechsel = Neuanfang. Ein MCP Server kapselt Tool-Fähigkeiten in einem eigenen Prozess: einmal schreiben, nutzen in Claude Desktop, Cursor und Gemini.

Typische Szenarien: Postgres-Verkaufsdaten aus Claude Desktop abfragen; Cursor-Agent liest Projekt-Docs und ändert Code; GPT ruft Ihr Ticketsystem per HTTP-MCP auf — alles über denselben Server.

Was dieser Leitfaden liefert: nicht nur Konzept, sondern den Pfad von say_hello bis zum produktionsreifen Wissensbasis-Server mit Vektorsuche. Zielgruppe: Entwickler mit Python- oder TypeScript-Basis, die KI in IDE oder Desktop erweitern wollen.

Sechs Pain Points: Warum API-Wrapper allein nicht reichen

1. 01

   Anbieter-Lock-in: OpenAI Function Calling und Claude Tool Use nutzen unterschiedliche Formate — jeder Wechsel erfordert eine neue Adapter-Schicht.

2. 02

   Tools nicht auffindbar: REST-APIs hängen an statischen Docs; KI kann zur Laufzeit kein tools/list aufrufen, um Fähigkeiten selbst zu entdecken.

3. 03

   IDE-Silos: Cursor, VS Code-Erweiterungen und JetBrains-Plugins definieren Tools jeweils anders — Sie pflegen N×M-Integrationen.

4. 04

   Kontext und Daten getrennt: LLMs lesen Konfiguration, Nutzerprofile oder Live-Logs nicht zuverlässig — standardisierte Nur-Lese-Resources sind nötig.

5. 05

   Prompt-Vorlagen verstreut: Code Review und Incident-Reports haben kein zentrales Register; Teams kopieren unabhängig.

6. 06

   Lokal vs. Remote chaotisch: stdio-Kindprozesse passen zur Entwicklung; Produktions-HTTP-Gateways, Auth und Monitoring fehlen oft ein gemeinsames Muster (siehe stdio-Subprozess-Management).

Entwicklungsumgebung: Python FastMCP vs TypeScript SDK

Zwei Hauptrouten: Python mcp + FastMCP (daten-/skriptfreundlich) und TypeScript @modelcontextprotocol/sdk (Web/API-Integration, Typsicherheit). SDK-Repos: python-sdk, typescript-sdk.

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

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

Empfohlene Projektstruktur

my-mcp-server/
├── pyproject.toml          # oder package.json
├── src/
│   ├── server.py           # FastMCP-Einstieg
│   ├── tools/              # Tool-Module
│   ├── resources/          # Resource-Provider
│   └── prompts/            # Prompt-Vorlagen
├── tests/
│   └── test_tools.py       # pytest + ClientSession
├── Dockerfile
└── README.md

Sechs-Schritte-Umgebungs-Checkliste

1. 01

   Stack wählen: Daten-/ML-Teams bevorzugen Python; Node-Fullstack-Teams TypeScript.

2. 02

   Virtuelle Umgebung und Dependency-Lock: pip freeze oder package-lock.json, um Schema-Drift zu vermeiden.

3. 03

   MCP Inspector installieren: npx @modelcontextprotocol/inspector für visuelles JSON-RPC-Debugging.

4. 04

   Claude Desktop konfigurieren: ~/Library/Application Support/Claude/claude_desktop_config.json bearbeiten und Server command/args hinzufügen.

5. 05

   Cursor konfigurieren: Settings → MCP → Add Server; für stdio python -m src.server oder absoluten Pfad.

6. 06

   Inspector-Verbindung prüfen: Server starten → Inspector verbinden → tools/list liefert nicht-leere Liste.

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

Tools vertieft: Von Schema bis fünf produktionsreife Tools

Tools sind MCPs Kernfähigkeit: KI führt Seiteneffekt-Operationen per tools/call aus. Jedes Tool exponiert Name, Beschreibung und inputSchema; FastMCP nutzt Pydantic-Modelle zur Validierung.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="Suchbegriff")
    limit: int = Field(10, ge=1, le=100, description="Max. Treffer")

@mcp.tool()
async def search_docs(params: SearchInput) -> str:
    """Suche in der Dokumentenbibliothek"""
    results = await index.search(params.query, params.limit)
    return json.dumps(results, ensure_ascii=False)

Fünf häufige Tool-Muster

• calculator: sicheres eval oder ast.literal_eval; niemals exec.
• file_read / file_write: Root-Verzeichnis-Whitelist gegen Path Traversal.
• fetch_url (async): httpx mit Timeout und Domain-Whitelist.
• db_query: Nur-Lese-SQL mit parametrisierten Queries; kein DDL.
• get_current_time: ISO8601 mit Zeitzone gegen LLM-Zeit-Halluzination.

import httpx
from datetime import datetime, timezone

@mcp.tool()
async def fetch_url(url: str) -> str:
    """HTTP GET für URL-Inhalt (Domain-Whitelist)"""
    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:
    """Aktuelle UTC-Zeit"""
    return datetime.now(timezone.utc).isoformat()

Fehlerbehandlung: Best Practices

• Strukturierte Fehler: raise ValueError("human-readable msg"); Client gibt Message an LLM zurück.
• Retryable vs. fatal trennen: Netzwerk-Timeout als retryable; Berechtigungsverweigerung sofort fail.
• Logging und Redaktion: Tool-Name und Latenz loggen; keine vollständigen API-Keys oder PII — besonders relevant unter DSGVO.
• Idempotenz: Schreiboperationen mit idempotency_key, um doppelte Agent-Aufrufe zu vermeiden.

Prompts: Wiederverwendbare mehrstufige Dialogvorlagen

Ein MCP-Prompt ist ein auf dem Server registriertes Dialog-Skelett. Der Client holt per prompts/get eine Message-Liste mit user / assistant und Parameter-Platzhaltern — Teams teilen Code Review und Incident-Workflows ohne pro-Nutzer-Prompt-Dateien.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str = "python") -> list[PromptMessage]:
    """Standardisiertes Code-Review-Mehrstufig-Template"""
    return [
        PromptMessage(role="user", content=TextContent(
            type="text",
            text=f"Du bist Senior-{language}-Entwickler. Prüfe den Diff nach Sicherheit, Performance und Lesbarkeit."
        )),
        PromptMessage(role="assistant", content=TextContent(
            type="text",
            text="Bitte Diff einfügen oder PR-Nummer nennen — ich liefere strukturiertes Review per CHECKLIST."
        )),
    ]

Mehrstufige Templates können Variablen nesten ({ticket_id}, {severity}). Der Server verwaltet Versionen; Client-Upgrade des Servers synchronisiert Review-Standards im Team.

Debugging und Tests: Inspector + pytest Unit-Tests

MCP Inspector ist der offizielle visuelle Debugger: per stdio oder URL verbinden, tools/list und tools/call manuell senden, JSON-RPC-Roundtrips prüfen — deutlich schneller als Cursor-Logs interpretieren.

# 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

Häufige Fehler: Referenz

Praxisprojekt: ChromaDB-Wissensbasis MCP Server

Interne Wiki- und Markdown-Docs vektorisieren und index_document, search_knowledge und write_note als Tools exponieren — Cursor-Agent kann „erst Firmenwissen suchen, dann Code schreiben“.

Anforderungen: inkrementelle Indexierung (watchfiles auf docs/), semantische Top-K-Suche, optional Scratchpad-Schreiben.

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:
    """Semantische Suche in interner Wissensbasis"""
    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:
    """Einzelne Markdown-Datei indexieren"""
    text = open(path).read()
    collection.upsert(ids=[path], documents=[text], metadatas=[{"path": path}])
    return f"Indexed: {path}"

Cursor-Demo-Query: „Suche in der Wissensbasis Docs zu MCP-HTTP-Deployment und fasse eine Drei-Schritte-Go-Live-Checkliste zusammen“ — Agent ruft zuerst search_knowledge auf. Größere Skalierung: Vektorstore auf Qdrant (Remote gRPC). Interne Dokumente nur auf isolierten Instanzen indexieren, wenn DSGVO oder Vertraulichkeit greifen.