MCP Server von Grund auf entwickeln: Ein vollständiger Entwicklerleitfaden

Große Sprachmodelle sind stark im Text-Reasoning, bleiben aber bewusst von Live-Systemen isoliert. Jeder nützliche Agenten-Workflow — „Kunde im CRM nachschlagen", „fehlschlagende Testdatei öffnen", „Slack-Thread der letzten Woche zusammenfassen" — braucht einen programmatischen Hook, den das Modell sicher entdecken und aufrufen kann.

Die Branche probierte mehrere Antworten. Function Calling band Tool-Schemas an eine einzelne Vendor-API. Plugins sperrten Sie in den Marketplace eines Produkts. Agent-Frameworks wie LangChain abstrahierten Tools, aber nicht den Transport — Host-Wechsel bedeutete weiterhin Glue-Code neu schreiben. MCP, von Anthropic im November 2024 veröffentlicht, standardisiert das Wire-Format: Server einmal schreiben, von Cursor, Claude Desktop, VS Code oder jedem konformen Client anbinden. Am Ende dieses Leitfadens haben Sie einen selbst gebaut und deployed.

• Doppelte Adapter pro Host: Dateisystem-Zugriff, Datenbankabfragen und API-Wrapper werden separat für Cursor, Claude Desktop und Continue neu implementiert.
• Vendor-Lock-in bei Schemas: Tool-Definitionen im OpenAI-Function-Format reisen nicht mit, wenn Sie Claude oder Gemini einführen.
• Keine first-class Read-only-Daten: Function Calling deckt „etwas tun" ab, nicht „diese Config-Datei als Kontext bereitstellen" — erzwungene Workarounds.
• Undurchsichtiges Debugging: Scheitert ein Tool-Aufruf mitten in der Agenten-Schleife, fehlt ein gemeinsamer Inspector oder JSON-RPC-Trace.

Ein MCP Client lebt innerhalb der Host-Anwendung (Cursor, Claude Desktop, ein eigener Agent-Runner). Ihr MCP Server ist der von Ihnen geschriebene Prozess — er exponiert Fähigkeiten und verbindet zu echten Systemen. Kommunikation über JSON-RPC 2.0 via stdio (lokaler Subprozess) oder HTTP + SSE (Remote-Dienst). Session-Lifecycle: Initialize-Handshake → Capability-Negotiation → Request/Response-Schleife → Graceful Shutdown.

Jeder MCP Server bewirbt bis zu drei Capability-Typen:

• Tools: Aufrufbare Funktionen — Suche, Berechnung, Datenbank-Schreibzugriff.
• Resources: Read-only-Daten per URI — Dateien, Configs, API-Snapshots.
• Prompts: Wiederverwendbare Prompt-Vorlagen mit Parameter-Slots.

Python ist der schnellste Pfad für die meisten Backend-Ingenieure — das offizielle mcp-Paket mit FastMCP-Dekoratoren hält Boilerplate minimal. TypeScript passt zu Teams auf Node: @modelcontextprotocol/sdk installieren und dieselben Muster spiegeln. Dieser Leitfaden nutzt Python als Primärsprache mit TypeScript-Hinweisen bei Abweichungen.

# Python
python -m venv .venv
source .venv/bin/activate
pip install mcp httpx pydantic

# TypeScript (Referenz)
npm init -y
npm install @modelcontextprotocol/sdk

Empfohlenes Projekt-Layout:

my-mcp-server/
├── server.py
├── tools/
│   ├── calculator.py
│   └── web_search.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

Debug-Stack: MCP Inspector (offizielle Browser-UI), Claude Desktop für lokale Integrationstests und Cursors .cursor/mcp.json für IDE-seitige Validierung. Vollständige Spezifikation unter modelcontextprotocol.io.

FastMCP macht aus einer Python-Funktion per Dekorator ein entdeckbares Tool. Funktionssignatur und Docstring werden zum JSON Schema, das das Modell zur Laufzeit liest.

from mcp.server.fastmcp import FastMCP

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

@mcp.tool()
def say_hello(name: str) -> str:
    """Begrüßt eine Person beim Namen."""
    return f"Hallo, {name}! Das ist Ihr erstes MCP-Tool."

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

python server.py
npx @modelcontextprotocol/inspector python server.py

Einbindung in Cursor via .cursor/mcp.json oder Claude Desktop via claude_desktop_config.json mit command + args auf python server.py. Host neu starten und prüfen, dass das Tool im MCP-Panel erscheint, bevor das Modell es aufruft.

Behandeln Sie jedes Tool als öffentliche API: klare Benennung (snake_case), typisierte Parameter, beschreibende Docstrings und strukturierte Fehlerantworten statt roher Stacktraces. FastMCP introspektiert Type Hints; für komplexe Inputs Pydantic-Modelle nutzen.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Suchbegriffe")
    max_results: int = Field(default=5, description="Maximale Anzahl Ergebnisse")
    language: str = Field(default="de", description="Sprachcode der Ergebnisse")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """Führt eine Websuche aus und liefert passende Treffer."""
    ...

Fünf Starter-Tools als Übungsliste:

• Rechner: Mathematische Ausdrücke auswerten (eval sandboxen — niemals unsanitized Input durchreichen).
• Datei-I/O: Lesen und Schreiben innerhalb eines Allowlist-Verzeichnisses.
• HTTP-Client: Aufrufe an externe REST-APIs proxen.
• Datenbankabfrage: Read-only SQL gegen konfigurierte DSN ausführen.
• Datetime-Utility: Aktuelle Zeit, Zeitzonen-Konvertierung, ISO-Formatierung.

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Ruft den Body einer URL ab und gibt ihn zurück."""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.text

Produktionsgewohnheiten: 30-Sekunden-Timeout bei I/O-gebundenen Tools, Berechtigungen serverseitig prüfen, API-Keys auf dem Server halten — niemals in Client-Config-Dateien.

Resources unterscheiden sich von Tools: Eine Resource liefert Daten; ein Tool führt eine Aktion aus. Resources werden per URI-Schema adressiert — file://, https:// oder Custom-Schemes wie config:// — und der Client holt sie ohne Nebenwirkungen.

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    user = db.query_user(user_id)
    return json.dumps(user)

Unterstützte MIME-Typen: text/plain, application/json und Binärformate für Bilder oder PDFs. Ein Filesystem-Resource-Server implementiert typischerweise Verzeichnislisting, Datei-Lesezugriff und optionale Change-Subscriptions, damit der Client bei Dateiänderungen aktualisiert.

MCP Prompts sind parametrisierte Message-Vorlagen, die der Host Nutzern oder Agenten anbieten kann. Sie standardisieren wiederkehrende Workflows — Code-Review, Incident-Triage, Interview-Vorbereitung — ohne Anweisungen in jede Session zu kopieren.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"Prüfe den folgenden {language}-Code auf Bugs, "
                     f"Sicherheitslücken und Stil. Gib zeilenbezogenes Feedback:\n\n{code}"
            )
        )
    ]

Multi-Turn-Vorlagen können sowohl user- als auch assistant-Rollen enthalten und strukturierte Dialoge liefern, die der Host als einzelnen wählbaren Prompt rendert.

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

Remote-Deployments brauchen Bearer-Token-Authentifizierung, Rate Limiting, CORS-Policy und TLS-Terminierung am Reverse Proxy. Secrets zentral auf dem Server — Clients halten nur Verbindungs-URLs und rollenspezifische Auth-Tokens.

Zitierbarer Datenpunkt 1: Stand 2026 listet das öffentliche MCP-Ökosystem über 10.000 Server — jeder sofort von jedem konformen Host ohne zusätzlichen Adapter-Code aufrufbar.

Zitierbarer Datenpunkt 2: Teams, die MCP für interne Tool-Integration einführen, berichten Entwicklungskostenreduktionen von 38–55 % gegenüber per-Vendor-Custom-Adaptern (Branchenumfrage 2025–2026).

Zitierbarer Datenpunkt 3: Das offizielle MCP-Python-SDK überschritt in Q2 2026 5 Millionen monatliche PyPI-Downloads — praktisches Signal, dass serverseitige MCP-Entwicklung vom Experiment zum Default-Stack geworden ist.

MCP Inspector startet eine Browser-UI gegen Ihren Server-Prozess: Tool-Inventar durchsuchen, Testaufrufe feuern und rohe JSON-RPC Request/Response-Paare inspizieren. Für CI den Server als Subprozess starten und programmatisch ansteuern:

from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async with stdio_client(StdioServerParameters(
    command="python", args=["server.py"]
)) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("calculate", {"expression": "2 + 2"})
        assert result.content[0].text == "4"

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

Deployment-Ziele nach Skalierung: Railway / Render für Solo-Projekte mit minimalem Ops-Aufwand; AWS Lambda / Google Cloud Run für event-getriebene oder burstige Workloads; Self-hosted VPS oder Cloud-Mac mit Nginx-Reverse-Proxy, wenn persistente SSE-Sessions und niedrige Tool-Call-Latenz nötig sind.

Observability-Checkliste: strukturierte JSON-Logs pro tools/call, Prometheus-Counter für Call-Volumen und Latenz, Sentry für unbehandelte Exceptions und ein /health-Endpunkt für Load-Balancer-Probes. MCP-Protokollversion in Server-Metadaten pinnen; Tool-Schema-Änderungen als Semver behandeln — additive Felder sind sicher, Parameter-Entfernung bricht Downstream-Agenten.

Ziel: Jeder MCP-Host soll lokale Markdown-Notizen durchsuchen, semantisch ähnliche Passagen abrufen und Dateien auf Befehl erstellen oder aktualisieren können.

Stack-Wahl: ChromaDB oder Qdrant für lokale Vektorspeicherung; text-embedding-3-small für Embeddings; watchfiles zum Re-Indexieren bei Speichern.

• Index-Tool: Notizen-Verzeichnis scannen, Markdown chunken, embedden und in Vector Store upserten.
• Semantisches Such-Tool: Natürlichsprachliche Query annehmen; Top-K-relevante Chunks mit Quellpfaden zurückgeben.
• Schreib-Tool: Markdown-Datei im Allowlist-Ordner erstellen oder anhängen.
• Resource-Handler: Vollständigen Notiz-Inhalt via note://{filename}-URIs für Direkt-Lesezugriff exponieren.

Demo-Szenario: In Cursor fragen „Was habe ich letzte Woche über MCP-Deployment notiert?" — der Agent ruft Ihr Such-Tool auf, erhält gerankte Snippets und synthetisiert eine Antwort aus Ihren echten Notizen statt aus Trainingsdaten.

Community-Server zum Studieren: mcp-server-filesystem (Verzeichniszugriff), mcp-server-github (Repo-Operationen), mcp-server-brave-search (Websuche), mcp-server-postgres (SQL) und mcp-server-slack (Messaging).

2026-Trajektorie: OpenAI, Google und Microsoft haben MCP-Support zugesagt; Governance liegt bei der Linux Foundation unter AAIF; MCP-Marketplaces wachsen schnell; Enterprise-OAuth-2.1-Integration steht auf der nahen Roadmap.

Lernpfad nach diesem Leitfaden: Vollständige MCP-Spezifikation lesen; Server in Registry veröffentlichen; MCP mit Agenten-Orchestrierungsmustern aus unserem Cursor Agent Skills Guide kombinieren; zu Python SDK, TypeScript SDK oder Inspector beitragen.

1. 01
   Transportmodus wählen: stdio für solo lokale Entwicklung. Auf HTTP+SSE wechseln, wenn mehrere Teammitglieder oder Remote-Agenten denselben Server brauchen — API-Keys zentral auf dem Server halten, nicht in jeder Laptop-Config.
2. 02
   Cloud-Mac in der Konsole bereitstellen: In der NUKCLOUD-Konsole anmelden und 16 GB+ Unified-Memory-Tier wählen (32 GB bei parallelen MCP-Server-Prozessen). Stundenweise testen auf der Preisseite.
3. 03
   Python 3.12 und Abhängigkeiten installieren: Per SSH einloggen, pip install mcp httpx pydantic ausführen, Server-Repo klonen und lokal mit MCP Inspector smoke-testen, bevor ein Port exponiert wird.
4. 04
   HTTP-Server deployen und Port öffnen: Mit mcp.run(host="0.0.0.0", port=8000) hinter Nginx-TLS-Terminierung starten. Bearer-Token-Middleware, CORS-Regeln und Rate Limits hinzufügen, bevor die URL geteilt wird.
5. 05
   Clients verbinden und validieren: Cursor .cursor/mcp.json oder Claude-Desktop-Config auf Cloud-Endpunkt zeigen. tools/list muss Inventar liefern; einen tools/call-Smoke-Test ausführen und Baseline-Latenz protokollieren.
6. 06
   Prozess mit launchd am Leben halten: ~/Library/LaunchAgents/com.team.mcp-server.plist für 7×24-Uptime schreiben. Nach dem Pilot Tier auf der Bestellseite fixieren. Knoten-Details im NUKCLOUD-Produktions-Runbook.

HTTP-MCP-Server auf lokalem MacBook oder geteiltem VPS scheitern routinemäßig an Deckel-zu-Sleep, der SSE-Sessions killt, Bandbreiten-Jitter bei langen Verbindungen und Port-Konflikten bei mehreren Entwicklern auf einer Maschine. Wenn Cursor Background Agents oder ein persönlicher Wissensdatenbank-Server stabile 7×24-Tool-Zugriffe brauchen, liefern NUKCLOUD Multi-Region-Bare-Metal-Mac- / Cloud-Mac-Knoten Mandantenisolation und Spez-Elastizität im Einklang mit MCP-Workflows — stundenweise für Piloten starten, dann auf feste Monatskapazität wechseln.