Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Architektur eines benutzerdefinierten MCP-Servers

Lektion 10 von 14 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Design eines produktionsreifen MCP-Servers
  2. Auswahl des Frameworks
  3. Eine Projektstruktur, die hält
  4. Der Einstiegspunkt: server.py
  5. Ein Tools-Modul pro Bereich
  6. Zentrale Konfiguration
  7. Fehler, die das Modell lesen kann
  8. Zustandsbehaftet oder zustandslos
  9. Kernaussagen

Aktualisiert am 2. November 2026 — MCP Python SDK v2. Dieser Kurs folgt nun Version 2 des mcp SDK (Stand 2.3.0 vom 2. Oktober 2026): MCPServer ersetzt FastMCP, Transport-Einstellungen werden in run() oder streamable_http_app() verlegt, und eine Anwendung, die unter einem echten Hostnamen bereitgestellt wird, muss diesen Hostnamen deklarieren (transport_security). Dies ist auch die vom Mistral SDK erforderliche Version: Das mistralai[agents]-Extra benötigt mcp>=2.2.0,<3.0. Quellen: Was ist neu in v2 · Migrationsanleitung · Bereitstellen und skalieren.

Design eines produktionsreifen MCP-Servers

Ein MCP-Prototyp passt in eine Datei mit vierzig Zeilen, und das reicht oft aus, um ein Team zu überzeugen. Der Wechsel zur realen Nutzung ändert jedoch alles: Mehrere Personen rufen den Server auf, die Anzahl der Tools vervielfacht sich, die Konfiguration variiert je nach Umgebung, und die einzelne Datei wird unübersichtlich. Diese Lektion behandelt die architektonischen Entscheidungen, die verhindern, dass man an dieser Grenze ankommt: Auswahl eines Frameworks, Strukturierung des Projekts, Verwaltung von Konfiguration und Fehlern sowie die Entscheidung zwischen zustandsbehafteten und zustandslosen Servern.

Auswahl des Frameworks

In Python ist die MCPServer-Klasse des offiziellen SDKs (ehemals FastMCP) das Standardwerkzeug. Sie bietet eine dekoratorbasierte API und übernimmt das MCP-Protokoll für Sie, sodass ein Server in drei Zeilen zum Leben erweckt wird:

from mcp.server.mcpserver import MCPServer

app = MCPServer(
    "My Server",
    instructions="MCP Server für Projektmanagement",
)

Teams, die JavaScript und TypeScript nutzen, verfügen über das offizielle MCP SDK von Anthropic. Die Logik ist vergleichbar, auch wenn die Syntax abweicht:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "My Server",
  version: "1.0.0",
});

Die Entscheidung hängt weniger von den Fähigkeiten ab als vielmehr vom Ökosystem, in dem Ihr Server seine Daten abruft. Ein Server, der über SQLAlchemy eine Datenbank abfragt oder bestehende Verarbeitungsskripte wiederverwendet, wird natürlich in Python geschrieben; ein Server, der auf einer bestehenden Express-Anwendung aufbaut, bleibt in TypeScript. Die folgende Tabelle fasst die praktischen Unterschiede zusammen.

KriteriumMCPServer (Python SDK)MCP SDK (TypeScript)
ReifeSehr reifReif
Dekoratoren@app.tool()server.tool()-Methode
HTTP-TransportEingebaut (FastAPI)Eingebaut (Express)
CommunityGroßGroß

Eine Projektstruktur, die hält

Die empfohlene Verzeichnisstruktur trennt vier Verantwortlichkeiten: Was das Modell sieht (tools/), was auf Daten zugreift (services/), was den Zugriff steuert (auth/) und was die Umgebung beschreibt (config.py, .env).

my-mcp-server/
├── server.py              # FastAPI-Einstiegspunkt + MCP-Montage
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Projektmanagement-Tools
│   ├── file_tools.py      # Dateiverwaltungs-Tools
│   └── search_tools.py    # Such-Tools
├── services/
│   ├── __init__.py
│   ├── database.py        # Datenbankzugriff
│   └── external_api.py    # Aufrufe externer APIs
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Authentifizierungs-Middleware
├── config.py              # Konfiguration (Umgebungsvariablen)
├── Dockerfile             # Containerisierung
├── requirements.txt       # Python-Abhängigkeiten
├── .env                   # Umgebungsvariablen (nicht committed)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Diese Trennung hat eine direkte, konkrete Konsequenz: Ihre Tools enthalten keine SQL- oder HTTP-Aufrufe mehr, sondern nur noch Validierung und Delegation an einen Dienst. Sie können dann die Geschäftslogik testen, ohne über MCP zu gehen, und Datenbanken austauschen, ohne eine einzige Docstring-Anweisung zu ändern, die das Modell sieht.

Der Einstiegspunkt: server.py

Die Hauptdatei tut nichts anderes als Komponenten zusammenzusetzen: Sie erstellt die FastAPI-Anwendung, stapelt Middlewares und montiert jeden MCP-Server an seinem eigenen Route-Pfad.

# server.py
"""MCP-Server-Einstiegspunkt."""

from contextlib import asynccontextmanager

import os

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from mcp.server.transport_security import TransportSecuritySettings
from tools.project_tools import project_mcp
from tools.search_tools import search_mcp
from auth.middleware import AuthMiddleware

# Jeder MCP-Server muss seinen Session-Manager starten
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# FastAPI-Anwendung
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS für Web-Clients
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Authentifizierungs-Middleware
api.add_middleware(AuthMiddleware)

# Öffentlicher Hostname, unter dem Server bereitgestellt werden (sonst: 421 Ungültiger Host-Header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# MCP-Server an unterschiedlichen Routen montieren
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Startseite (optional, aber nützlich)
@api.get("/")
async def root():
    return {
        "service": "My MCP Server",
        "version": "1.0.0",
        "endpoints": {
            "projects": "/projects/mcp",
            "search": "/search/mcp",
        },
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(api, host="0.0.0.0", port=8000)

Die Montage an unterschiedlichen Routen ermöglicht es Nutzern, nur den Bereich zu aktivieren, den sie benötigen: Jemand, der nach Dokumentation sucht, verbindet sich mit /search/mcp, ohne Projektmanagement-Tools angeboten zu bekommen. Was die Startseite betrifft, scheint sie trivial, bis ein Kollege nach der genauen Endpunkt-URL fragt; sie antwortet für Sie und dient als Gesundheitscheck.

Ein Tools-Modul pro Bereich

Jede Datei im tools/-Ordner deklariert ihren eigenen MCPServer-Objekt und gruppiert Tools desselben funktionalen Bereichs. Hier ist das Modul für Projektmanagement, das zuvor von server.py importiert wurde:

# tools/project_tools.py
"""MCP-Tools für Projektmanagement."""

from mcp.server.mcpserver import MCPServer
from services.database import db

project_mcp = MCPServer(
    "Project Manager",
    instructions="Tools für Projekt- und Aufgabenverwaltung",
)

@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
    """Erstellt ein neues Projekt.

    Args:
        name: Projektname (2–100 Zeichen)
        description: Projektdescription (optional)

    Returns:
        JSON mit Details des erstellten Projekts
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Listet Projekte nach Status auf.

    Args:
        status: Filter nach Status: active, archived, all (Standard: active)

    Returns:
        JSON mit Liste der Projekte
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Beachten Sie, wie kurz die Funktionskörper sind: jeweils nur zwei Zeilen, da der Datenzugriff in services/database.py liegt. Das Tool beschreibt lediglich seinen Vertrag für das Modell und delegiert.

Zentrale Konfiguration

Jeder Wert, der zwischen Ihrer Maschine und dem Produktionsserver variiert, muss aus der Umgebung kommen, niemals aus dem Code. Eine einzelne config.py-Datei sammelt diese Variablen mit ihren Standardwerten:

# config.py
"""MCP-Server-Konfiguration."""

import os
from dataclasses import dataclass

@dataclass
class Config:
    api_token: str = os.getenv("MCP_API_TOKEN", "")
    database_url: str = os.getenv("DATABASE_URL", "sqlite:///data.db")
    debug: bool = os.getenv("DEBUG", "false").lower() == "true"
    port: int = int(os.getenv("PORT", "8000"))
    max_results: int = int(os.getenv("MAX_RESULTS", "50"))

config = Config()

Der Parameter max_results veranschaulicht den Vorteil dieses Ansatzes: Wenn ein Tool eines Tages zu viele Ergebnisse zurückgibt und den Kontext des Modells überlastet, passen Sie eine Umgebungsvariable an und starten neu, ohne Code neu zu deployen.

Fehler, die das Modell lesen kann

Eine Python-Ausnahme, die abrupt aufblubert, sagt dem Modell nichts: Es sieht einen Fehler, versteht aber nicht warum, und versucht oft identisch erneut. Stattdessen standardisieren Sie ein explizites Fehlerantwortformat mit einem Code und einer Nachricht.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formatiert eine standardisierte Fehlermeldung."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Ruft Projektdetails nach ID ab."""
    try:
        project = await db.projects.get(project_id)
        if not project:
            return error_response(f"Projekt {project_id} nicht gefunden", "not_found")
        return project.to_json()
    except Exception as e:
        return error_response(f"Serverfehler: {str(e)}", "server_error")

Der Unterschied ist in der Konversation entscheidend. Angesichts von not_found versteht das Modell, dass es zuerst Projekte auflisten muss, um die richtige ID zu finden; angesichts einer stummen Ausnahme gibt es auf oder läuft in Schleife.

Zustandsbehaftet oder zustandslos

Ein zustandsbehafteter Server behält Informationen zwischen Aufrufen bei: In-Datenbank, Benutzersitzungen, Arbeitskontext. Dies ist bei Verwaltungsservern üblich, wie dem Aufgabenmanager aus der vorherigen Lektion. Ein zustandsloser Server behandelt jede Anfrage unabhängig, merkt sich nichts – empfohlen für reine Berechnungen oder Transformationen und ermöglicht horizontale Skalierung, da jede Instanz jede Anfrage bearbeiten kann. SDK v2 ermöglicht dies mit einem Parameter für die HTTP-Anwendung (nicht mehr an den Konstruktor übergeben). Beachten Sie, dass mit der Spezifikation vom 28. Juli 2026 das Protokoll selbst keine Sitzungen mehr kennt: Diese Einstellung betrifft nur Clients, die eine frühere Protokollversion verhandeln.

app = MCPServer("Stateless Server")

# Einstellung wird beim Aufbau der HTTP-Anwendung übergeben
mcp_app = app.streamable_http_app(stateless_http=True)

Entscheiden Sie sich für diese Frage, bevor Sie Ihre Tools schreiben, nicht danach: Der Wechsel von einem zustandsbehafteten zu einem zustandslosen Server bedeutet, dass Sie alle Zustände in eine externe Datenbank verlagern, was einen guten Teil des Codes umschreibt.

Kernaussagen

  • Trennen Sie Ihre Tools in thematische Module in einem tools/-Ordner
  • Verwenden Sie FastAPI als HTTP-Grundlage, montieren Sie MCP-Server an dedizierten Routen und übergeben Sie deren lifespan
  • Zentrieren Sie die Konfiguration über Umgebungsvariablen
  • Standardisieren Sie Fehlerantwort-Formate, damit das Modell sie nutzen kann
  • Entscheiden Sie sich zwischen zustandsbehaftet (Datenverwaltung) und zustandslos (reine Berechnung)
  • Fügen Sie eine /-Startseite hinzu, um Ihre MCP-Endpunkte zu dokumentieren