MCP Server von Grund auf:
Vollständiger Entwicklerleitfaden für AI-Tool-Aufrufe

Als Python- oder TypeScript-Entwickler möchten Sie Claude, GPT oder Cursor-Zugänge an Datenbanken, APIs und Dateisysteme anbinden — doch das Modell selbst hat keine «Hände»: Trainingsdaten haben Stichtage, externe Aktionen sind ohne Tooling unmöglich. Dieser Leitfaden führt von einem leeren Projekt zu einem produktionsfähigen MCP Server. Wir decken Tools, Resources und Prompts, stdio- sowie HTTP+SSE-Transport, Debugging, Tests und Docker-Deployment ab. Nach dem Lesen können Sie eigene Toolchains in Cursor oder Claude Desktop einbinden. Knoten und Pakete: NOVAKVM-Mietpreisseite.

[ SECTION_01 ] // WHAT_IS_MCP Was ist MCP: Von Function Calling zum einheitlichen Tool-Protokoll

Die KI-Tool-Integration durchlief drei Phasen: Function Calling (OpenAI, 2023) liefert strukturierte JSON-Aufrufparameter; Plugins / GPT Actions verpacken HTTP-Endpunkte als Dialog-Erweiterungen; MCP (Model Context Protocol) standardisiert seit Anthropics Open-Source-Veröffentlichung im November 2024, wie Modelle Tools entdecken, beschreiben und aufrufen — einmal implementiert, nutzbar in Claude Desktop, Cursor, VS Code Continue und weiteren Hosts.

• LLM-Fähigkeitsgrenze: Kein Live-Zugriff, kein direkter Datei- oder Datenbankzugriff — externe Tools liefern «Sinne und Hände».
• Format-Fragmentierung: OpenAI Function Calling, Claude Tool Use und LangChain Agents definieren jeweils eigene Tool-Schemas; Modell- oder IDE-Wechsel erzwingt Adapter-Neuschreiben.
• Fehlende Discovery: REST-APIs sagen dem Modell nicht, was sie können; MCP liefert zur Laufzeit über tools/list eine dynamische Fähigkeitsliste.
• Sitzung und Kontext: MCP hält persistente Verbindungen für mehrstufige Agent-Workflows; zustandslose REST-Aufrufe verkettet schwer.
• Sicherheit und Berechtigungen: Server-seitig steuerbar, welche Tools schreiben dürfen und welche Resources nur lesbar sind.

Die Client-Server-JSON-RPC-Architektur im Überblick:

• Host: Claude Desktop, Cursor, VS Code — Benutzeroberfläche.
• MCP Client: In den Host eingebettet, 1:1-Sitzung pro Server.
• MCP Server (Ihre Implementierung): Drei Primitive — Tools (ausführbare Aktionen), Resources (schreibgeschützte Daten), Prompts (wiederverwendbare Vorlagen).
• Transport: Lokal stdio (Subprozess stdin/stdout); remote HTTP + SSE (Server-Sent Events).
• Protokoll: JSON-RPC 2.0, z. B. initialize → tools/list → tools/call → notifications/cancelled.
• Lebenszyklus: Handshake → Capability-Negotiation → Betrieb → Graceful Shutdown; Client kann ping senden.

MCP löst nicht «kann man eine API aufrufen», sondern «wie entdeckt und wählt KI einheitlich Tools» — die Kernfrage der Agent-Ära.

[ SECTION_02 ] // DEV_ENV Entwicklungsumgebung: Python-mcp-SDK und TypeScript-SDK

Offizielle First-Class-SDKs: Python-Paket mcp (mit FastMCP-High-Level-API) und @modelcontextprotocol/sdk für TypeScript. Python eignet sich für schnelle Prototypen und Data/ML; TypeScript für Node.js- und Frontend-Teams. Im Folgenden Python FastMCP; die TypeScript-Struktur ist symmetrisch.

mkdir my-mcp-server && cd my-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic python-dotenv
npm install -g @modelcontextprotocol/inspector

Empfohlene Projektstruktur:

my-mcp-server/
├── server.py
├── tools/
├── resources/
├── prompts/
├── tests/
├── Dockerfile
├── requirements.txt
└── .env

Debugging und Anbindung — drei Werkzeuge:

• MCP Inspector: Offizieller visueller Debugger; listet tools/resources/prompts und erlaubt manuelle Aufrufe.
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) bearbeiten und stdio-Server registrieren.
• Cursor: Settings → MCP → Server-Konfiguration; stdio und remote HTTP werden unterstützt.

[ SECTION_03 ] // HELLO_WORLD Hello World: Erster MCP Server in zehn Zeilen

Minimaler FastMCP-Server mit Tool say_hello:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server")

@mcp.tool()
def say_hello(name: str) -> str:
    return f"Hello, {name}! MCP Server is running."

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

Validierung mit Inspector:

npx @modelcontextprotocol/inspector python server.py

Im Inspector-UI unter Tools say_hello mit {"name": "NOVAKVM"} aufrufen — erwartete Begrüßung.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "hello-server": {
      "command": "/path/to/my-mcp-server/.venv/bin/python",
      "args": ["/path/to/my-mcp-server/server.py"]
    }
  }
}

Cursor MCP: .cursor/mcp.json im Projektroot oder Settings → MCP; nach Neustart erscheint say_hello im Agent-Modus.

[ SECTION_04 ] // TOOLS Tools: Fünf Tool-Klassen und Fehlerbehandlung

Funktionssignatur ist Dokumentation: Parameternamen, Typannotationen und Docstrings werden zu JSON Schema für das Modell. Komplexe Eingaben per Pydantic:

from pydantic import BaseModel, Field

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

@mcp.tool()
async def search_docs(input: SearchInput) -> list[dict]:
    ...

Typische Produktions-Tools in fünf Kategorien:

• calculator: Sichere Auswertung mathematischer Ausdrücke; kein nacktes eval, stattdessen ast oder Speziallib.
• file_read / file_write: Wurzelverzeichnis begrenzen (Chroot-Denke); Schreibzugriff mit Bestätigung oder Extension-Whitelist.
• fetch_url: Asynchroner HTTP-Request, Beispiel unten.
• db_query: Nur-Lese-SQL (SELECT), parametrisiert gegen Injection; Schreibtools separat mit Audit-Log.
• get_current_time: ISO-8601-Zeitstempel — löst «welche Uhrzeit ist es?» für das Modell.

import httpx

@mcp.tool()
async def fetch_url(url: str, timeout: int = 30) -> str:
    async with httpx.AsyncClient(timeout=timeout) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:50000]

Fehlerbehandlung — Best Practices:

• Exceptions im Tool abfangen; strukturierte Fehlermeldung zurückgeben statt Prozessabbruch — der Client übergibt das Ergebnis ans Modell.
• Timeouts und Retry-Obergrenzen für externe APIs; Endlosschleifen durch Modell-Retries vermeiden.
• API Keys und Connection Strings nur aus Umgebungsvariablen; nie in Tool-Returns oder Resources.
• Schreibtools liefern Operations-Zusammenfassung (was geändert, betroffene Zeilen).

[ SECTION_05 ] // RESOURCES Resources: Schreibgeschützte Daten vs. ausführbare Tools

Resource vs. Tool: Resources sind schreibgeschützter Kontext (Konfiguration, Profile, Log-Ausschnitte), Abruf via resources/read; Tools sind ausführbare Operationen. Resources für Information, die das Modell sehen, aber nicht ändern soll.

URI-Schemes:

• config://app/settings — statische Konfiguration, bei Start registriert.
• user://{id}/profile — dynamische Vorlage, Server generiert Inhalt zur Laufzeit.
• file:// — Dateisystem-Mapping (Pfad-Sandbox erforderlich).

Vier MIME-Typen: text/plain, application/json, Binär-Blob (Base64), stream (Chunking für große Dateien).

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

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

Dateisystem-Server können Verzeichnisinhalte rekursiv registrieren — das Modell «sieht» Projektstruktur ohne einzelne read-Tool-Aufrufe pro Datei.

[ SECTION_06 ] // PROMPTS Prompts: Wiederverwendbare Mehr-Runden-Vorlagen

MCP-Prompts sind vordefinierte Vorlagen, die der Host auflistet und in den Dialog injiziert — geeignet für Code-Review, Incident-Postmortem, API-Design-Review. Parameterisiert, mit Mehr-Runden-Message-Struktur.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, focus: str = "security") -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"Prüfe den folgenden {language}-Code mit Fokus {focus}. Liste Probleme und Verbesserungen:\n\n"
            )
        )
    ]

Mehr-Runden-Beispiel: Runde 1 Rolle und Constraints, Runde 2 Code-Platzhalter, Runde 3 strukturiertes JSON (severity / file / line / suggestion). Teams kodifizieren Best Practices als Prompt statt jedes Mal System-Prompts neu zu schreiben.

[ SECTION_07 ] // HTTP_TRANSPORT HTTP-Transport: Von stdio zu Streamable HTTP

FastMCP unterstützt streamable-http — einzeiliger Wechsel:

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

Produktions-HTTP erfordert zusätzlich:

• Bearer Token / API Key: Authorization-Header in Reverse Proxy oder Middleware prüfen.
• CORS: Erlaubte Origins, wenn Browser-Inspector cross-origin zugreift.
• Rate Limiting: Pro IP oder API Key — Schutz vor Modell-Retry-Stürmen.
• TLS: HTTPS für öffentliche Endpunkte; Caddy oder Nginx als SSL-Terminator.

Bei Cloud-Deployment in der EU: Tool-Aufrufe können personenbezogene Daten aus CRM, Tickets oder Logs enthalten. DSGVO verlangt dann Auftragsverarbeitungsvertrag (AVV) mit dem PaaS-Anbieter, Dokumentation der Verarbeitungszwecke, Datenminimierung in Tool-Returns und — wo möglich — Hosting in EU-Rechenzentren oder On-Prem/VPS statt US-only-Free-Tier.

[ SECTION_08 ] // DEBUG_TEST Debug, Tests und Fehlerbehebung

MCP Inspector: Links die Server-Fähigkeitsliste; Tools-Panel für manuelle JSON-Aufrufe; Notifications für Server-Push; Logs für stderr. Nach Code-Änderung startet Inspector den Subprozess neu.

import pytest
from server import say_hello

def test_say_hello():
    result = say_hello("World")
    assert "Hello, World!" in result

@pytest.mark.asyncio
async def test_fetch_url():
    result = await fetch_url("https://httpbin.org/get")
    assert "origin" in result

Sechs-Schritte-Produktions-Checkliste:

1. Dependencies pinnen: pip freeze > requirements.txt; Python- und mcp-SDK-Version in CI fixieren.
2. Dockerfile: Multi-Stage-Build; Non-Root-User für den Server-Prozess.
3. Secrets: API Keys, DB-Strings, ALLOWED_PATHS über Secret Manager — keine Hardcodes.
4. Hosting wählen: Railway/Render für MVP; AWS Lambda + HTTP-Adapter für seltene Aufrufe; Cloud Run/VPS für 7×24 SSE — bei personenbezogenen Daten DSGVO-konforme Region und AVV prüfen.
5. Monitoring: Strukturierte JSON-Logs, /health, Prometheus oder Sentry.
6. Client-Verifikation: Remote-URL + Bearer Token in MCP-Config; tools/list vor Rollout.

[ SECTION_09 ] // PRODUCTION Produktionsbetrieb: Docker, Hosting und Observability

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

Hosting-Optionen:

• Railway / Render: Git-Push-Deploy; Free-Tier für MVP — Cold Start beeinträchtigt SSE-Langzeitverbindungen.
• AWS Lambda: Pay-per-Invoke; HTTP-to-stdio-Adapter nötig; ungeeignet für dauerhafte SSE.
• Google Cloud Run: Container-nativ; min-instances ≥ 1 für SSE-Stabilität.
• VPS / Bare Metal: Volle Netzwerk- und Datenträgerkontrolle; sinnvoll, wenn sensible Daten das interne Netz nicht verlassen dürfen — DSGVO-konforme Verarbeitung ohne Drittland-Transfer erleichtert.

Observability:

• Logging: structlog oder python-json-logger; pro Tool-Call name, duration_ms, status.
• Prometheus: Metriken mcp_tool_calls_total, mcp_tool_duration_seconds.
• Sentry: Unbehandelte Exceptions mit Server-Version-Tag für Rollback.

Versionskompatibilität: MCP-Spezifikation 2025-03-26 führte Streamable HTTP ein. Vor Deploy Client-Version (Cursor, Claude Desktop) und Server-SDK auf gleichen Transport prüfen. README mit mcp>=1.2.0 o. ä. dokumentieren.

[ SECTION_10 ] // ECOSYSTEM Praxis: ChromaDB-Wissensbasis und Ökosystem 2026

Integrationsprojekt — Wissensbasis-MCP-Server: ChromaDB oder Qdrant für Dokument-Vektoren, watchfiles für automatisches Re-Indexing bei Verzeichnisänderungen, Tools search_knowledge und write_note. In Cursor kann der Agent interne Dokumentation abfragen statt nur Trainingswissen.

@mcp.tool()
async def search_knowledge(query: str, top_k: int = 5) -> list[dict]:
    embedding = await embed(query)
    results = collection.query(query_embeddings=[embedding], n_results=top_k)
    return [{"text": doc, "score": score} for doc, score in zip(...)]

@mcp.tool()
async def write_note(title: str, content: str) -> str:
    doc_id = collection.add(documents=[content], metadatas=[{"title": title}])
    return f"Note saved: {doc_id}"

Community-MCP-Server zum Wiederverwenden:

• @modelcontextprotocol/server-filesystem — sandboxed Dateizugriff
• server-github — Issues, PRs, Code-Suche
• server-brave-search — Live-Websuche
• server-postgres — read-only SQL
• server-slack — Kanalnachrichten

Ökosystem-Kennzahlen 2026:

• Größe: Über 10.000 öffentliche MCP Server; modelcontextprotocol-Org auf GitHub zusammen über 50.000 Stars.
• Hersteller-Adoption: Q1 2026 OpenAI, Q2 Google Gemini und Microsoft Copilot mit nativer MCP-Unterstützung; Governance unter Linux Foundation AAIF.
• Integrationskosten: Branchenberichte nennen 38–55 % weniger Entwicklungsaufwand bei standardisierten MCP-Schnittstellen gegenüber N×M-Adaptern.

Lernpfad:

1. Offizielle Spezifikation und JSON-RPC-Nachrichtenfluss
2. FastMCP Hello World + Inspector
3. Mindestens drei echte Tools (Datei, HTTP, DB)
4. Resources und Prompts — Unterschiede der drei Primitive
5. HTTP-Transport, Docker-Deploy in Cloud oder VPS
6. Cursor-Anbindung: Wissensbasis oder GitHub-Integration

Verifizierbare Referenzen — bei Upstream-Updates Links prüfen:

Model Context Protocol — Spezifikation und Dokumentation

modelcontextprotocol/python-sdk — Python MCP SDK

modelcontextprotocol/typescript-sdk — TypeScript MCP SDK

modelcontextprotocol/inspector — MCP Inspector

MCP auf schlafenden Laptops oder instabilen Free-Tier-PaaS-Instanzen erzeugt typische Ausfälle: tools/list-Sitzungsabbruch, abgelaufene OAuth-Tokens, volle Platte mit korruptem Vektorindex, SSE-Disconnect nach Netzwerkwechsel — oft relevanter als die Modellwahl. Docker auf dem Laptop löst Host-Sleep nicht; Lambda passt schlecht zu dauerhaftem SSE.

Für 7×24 MCP-Toolchains, stabiles SSH und planbare Apple-Silicon-Leistung lohnt Migration auf dediziertes Bare Metal: NOVAKVM bietet Mac Mini M4 / M4 Pro in mehreren Regionen — geeignet für Cursor MCP, Claude Desktop Remote-Entwicklung und Vektorindex auf derselben Maschine. Pakete: Mietpreisseite, Bestellung: Bestellseite, Support: Hilfezentrum.