MCP Server von Null entwickeln: Vollständiger Entwicklerleitfaden

Große Sprachmodelle können weder Ihre Datenbank abfragen, interne APIs aufrufen noch lokale Dateien lesen — nicht aus mangelnder Intelligenz, sondern weil der standardisierte Tool-Kanal fehlt. Das Model Context Protocol (MCP) von Anthropic schließt diese Lücke: Claude, Cursor und GPT greifen über ein offenes Protokoll auf externe Fähigkeiten zu. Nach diesem Leitfaden entwickeln, debuggen und deployen Sie einen produktionsreifen MCP Server — inklusive Tools, Resources, Prompts, HTTP-Remote-Transport und DSGVO-bewusster Betriebsführung.

1. Drei Engpässe: Warum KI einen MCP Server braucht

Bevor Sie Code schreiben, definieren Sie die konkreten Probleme:

1. Tool-Inseln: Function Calling, Plugins und LangChain Tools nutzen jeweils eigene Formate — beim Modellwechsel fällt die Integrationschicht um. Klassisches N×M-Problem.
2. Daten nicht erreichbar: Trainingscutoff, keine Live-Konfiguration, keine internen Dokumente — und unter DSGVO keine unkontrollierte Cloud-Exfiltration sensibler Inhalte.
3. Aktionen nicht ausführbar: Reine Chat-KI sendet keine HTTP-Requests, schreibt keine Dateien, führt kein SQL aus — ohne standardisierte Tool-Schicht.

Wer bereits den MCP-Entscheidungsleitfaden gelesen hat, findet hier die Implementierung. Zielgruppe: Backend- und KI-Entwickler mit Python- oder TypeScript-Erfahrung.

2. Was ist MCP: Protokollprinzip und Architektur

2.1 Entstehung und Standardisierung

Die Tool-Integration evolvierte von Function Calling (OpenAI-proprietär) über Plugins (geschlossenes ChatGPT-Ökosystem) zu MCP (November 2024, Anthropic, offen). Kernziel: einmal implementieren, mehrere Clients nutzen — unter AAIF-Governance seit 2026 mit über 10.000 registrierten Servern.

2.2 Architektur: Client ↔ Server ↔ drei Fähigkeiten

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (Ihre Entwicklung) │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (Aktionen)   (Daten lesen)  (Prompt-Vorlagen)

• Client: KI-Seite — Claude Desktop, Cursor, VS Code, eigene Agenten.
• Server: Ihre Fähigkeiten — Tools, Resources, Prompts.
• Tools: Ausführbare Funktionen (Suche, Berechnung, DB-Query).
• Resources: Schreibgeschützte Daten per URI (file://, config://).
• Prompts: Parametrisierbare Prompt-Vorlagen für Team-Konsistenz.

2.3 Kommunikation und Lebenszyklus

MCP basiert auf JSON-RPC 2.0. Transport:

• stdio: Lokaler Subprozess, Latenz typisch <1 ms — ideal für Entwicklung.
• HTTP + SSE / Streamable HTTP: Remote, mehrere Clients, auditierbarer Zugriff.

Lebenszyklus: Initialize → Capability Negotiation (tools/list, resources/list) → Request/Response (tools/call) → Shutdown.

2.4 Vergleichsmatrix: MCP vs. Alternativen

3. Entwicklungsumgebung und Projektstruktur

3.1 Sprachwahl

• Python (Hauptsprache dieses Leitfadens): SDK mcp, FastMCP-Dekoratoren.
• TypeScript: SDK @modelcontextprotocol/sdk für Node/Full-Stack.

3.2 Umgebung

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

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

3.3 Empfohlene Projektstruktur

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

3.4 Debug-Werkzeuge

• MCP Inspector: Offizielle UI für Tools / Resources / Prompts.
• Claude Desktop: claude_desktop_config.json.
• Cursor: Settings → MCP oder .cursor/mcp.json.

4. Erster MCP Server: Hello World

4.1 Minimaler Server

from mcp.server.fastmcp import FastMCP

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

@mcp.tool()
def say_hello(name: str) -> str:
    """Begrüßt eine Person"""
    return f"Hello, {name}! Ihr erster MCP-Tool-Aufruf."

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

4.2 Start und Verifikation

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

Im Inspector prüfen: tools/list liefert say_hello; tools/call mit {"name": "Entwickler"} gibt die erwartete Antwort.

4.3 Anbindung an Cursor / Claude Desktop

{
  "mcpServers": {
    "my-first-server": {
      "command": "python",
      "args": ["/absoluter/pfad/zu/server.py"]
    }
  }
}

Nach Client-Neustart erscheint say_hello im Agent-Kontext. Verwenden Sie absolute Pfade — relative Pfade sind eine häufige Fehlerquelle bei instabilen stdio-Verbindungen.

5. Tools: Von der KI aufrufbare Funktionen

5.1 Struktur und Namenskonvention

Funktionssignatur und Docstring werden automatisch zu JSON Schema. Naming: snake_case, Verb zuerst (search_web, read_file).

5.2 Eingabe mit Pydantic

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Suchbegriff")
    max_results: int = Field(default=5, description="Max. Ergebnisse")
    language: str = Field(default="de", description="Ergebnissprache")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """Websuche mit strukturierten Ergebnissen"""
    ...

5.3 Fünf praxisnahe Tools

1. Rechner: Sichere Teilmenge von eval oder ast.literal_eval.
2. Dateizugriff: Whitelist-Verzeichnis, Schutz vor Path Traversal (Art. 32 DSGVO — technische Maßnahmen).
3. HTTP-Requests: httpx mit Timeout 30 s, keine Weiterleitung sensibler Header.
4. DB-Query: Nur SELECT, parametrisiert, kein DDL.
5. Zeitwerkzeuge: UTC mit datetime.now(timezone.utc).

5.4 Asynchrone Tools

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """URL-Inhalt abrufen"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.text

5.5 Fehlerbehandlung

• Strukturierte Fehler-JSON statt ungefangener Exceptions.
• Timeout für alle externen Aufrufe (empfohlen ≤30 s).
• Minimale Berechtigungen; Verarbeitungsprotokoll für Audit (Art. 30 DSGVO).

6. Resources: Dynamische Inhalte für die KI

6.1 Resource vs. Tool

Resources liefern Daten, Tools führen Aktionen aus. Keine Seiteneffekte bei Resource-Lesezugriffen — wichtig für Datenminimierung.

6.2 Statische und dynamische Resources

import json

@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)

6.3 Dateisystem-Ressourcen

Verzeichnis auflisten → Datei lesen → optional watchfiles für Update-Benachrichtigungen. Root-Whitelist konfigurieren; keine PII in Resource-URIs ohne Pseudonymisierung.

7. Prompts: Wiederverwendbare Vorlagen

7.1 MCP Prompts im Team

Vordefinierte Prompt-Fragmente mit Parametern — konsistente Code-Reviews und Dokumentation über alle Agent-Sessions.

7.2 Beispiel: Code-Review-Prompt

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"""Code-Review für {language}:
1. Lesbarkeit und Qualität
2. Sicherheitslücken (DSGVO-relevante Datenflüsse)
3. Performance

```{language}
{code}
```"""
            )
        )
    ]

8. HTTP-Transport: Remote MCP Server

8.1 stdio vs. HTTP+SSE

8.2 HTTP-Implementierung

from mcp.server.fastmcp import FastMCP

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

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

8.3 Sicherheit und DSGVO

• Bearer Token: Authorization: Bearer <token>.
• IP-Whitelist für interne Team-Clients.
• CORS: Nur vertrauenswürdige Origins.
• Rate Limiting: z. B. 10 tools/call pro Sekunde.
• Verarbeitungsverzeichnis: Welche Tools personenbezogene Daten lesen — dokumentieren.

9. Debugging, Tests und typische Fehler

9.1 Inspector-Workflow

1. npx @modelcontextprotocol/inspector python server.py
2. Tools / Resources / Prompts in der UI prüfen.
3. tools/call manuell auslösen, JSON validieren.
4. Fehlerszenarien (Timeout, ungültige Parameter) testen.

9.2 Unit-Test

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

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(server_params) 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"

9.3 Fehlermatrix

10. Produktion: Docker, Cloud und Monitoring

10.1 Docker

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"]

10.2 Hosting-Optionen 2026

• Railway / Render: Schnellstart, ca. 5–20 USD/Monat.
• Cloud Run / Lambda: Serverless, cold-start beachten.
• Remote Mac: launchd + Nginx, Apple-Ökosystem, stabile 7×24-Agent-Pipelines.

10.3 Observability

• Strukturierte Logs pro tools/call (Tool, Dauer, Status).
• Prometheus: Aufrufe, P99-Latenz, Fehlerrate.
• GET /health mit Protokollversion.

11. Praxisprojekt: Persönliche Wissensbasis als MCP Server

11.1 Anforderungen

• Semantische Suche in Markdown-Notizen.
• Notizen erstellen und aktualisieren (Whitelist-Pfad).
• DSGVO: Daten bleiben auf kontrolliertem Host.

11.2 Stack

• Vektordatenbank: ChromaDB oder Qdrant (embedded).
• Embeddings: text-embedding-3-small oder lokal nomic-embed-text.
• Dateiwächter: watchfiles für Index-Rebuild.

11.3 Kern-Tools

1. index_notes: Verzeichnis scannen, embedden, in Vektor-DB schreiben.
2. search_notes: Top-K semantische Treffer + Quellpfad.
3. write_note: Markdown anlegen (nur Whitelist).
4. notes://{path} Resource: Volltext lesen.

Ersparnis gegenüber vollem Context-Window: typisch 90 %+ Token, bei Echtzeit-Updates über watchfiles.

12. MCP-Ökosystem und Ausblick 2026

12.1 Empfohlene Community-Server

• mcp-server-filesystem: Dateisystem-Zugriff.
• mcp-server-github: Repos, Issues, PRs.
• mcp-server-brave-search: Websuche.
• mcp-server-postgres: Read-only SQL.
• mcp-server-slack: Nachrichten.

Spezifikation: modelcontextprotocol.io; Python SDK: github.com/modelcontextprotocol/python-sdk.

12.2 Trends

• Cursor, Claude Desktop, VS Code Copilot, Gemini CLI — native MCP-Unterstützung.
• AAIF-Zertifizierung und OAuth 2.1 für Enterprise.
• Feingranulare Tool-Berechtigungen und Audit-Logs.

12.3 Nächste Schritte

• MCP-Spezifikation vertiefen.
• Eigenen Server auf GitHub veröffentlichen.
• MCP + Agent kombinieren (Cursor Agent Skills).

13. Fazit: Vom Laptop-Experiment zum stabilen Produktionsknoten

Dieser Leitfaden deckt die gesamte Kette ab: Protokoll → Umgebung → Hello World → Tools / Resources / Prompts → HTTP → Inspector → Docker → Wissensbasis-Praxis. MCP ist der Standard für KI-Tooling im Jahr 2026.

Die Grenzen von stdio auf dem Entwicklungsrechner sind klar: Deckel zu → Verbindung weg; Vektor-Index und Embeddings belasten RAM und CPU; mehrere Server konkurrieren um Ressourcen. Wissensbasis-MCP, HTTP-Remote-Server und lange Agent-Sessions laufen auf einem dauerhaft online Apple-Silicon-Knoten stabiler — Unified Memory für Vektor-Suche, launchd für Prozessüberwachung, gleiche Toolchain wie Cursor und Claude Desktop.

SFTPMAC Remote-Mac-Miete liefert 7×24 Apple-Silicon-Umgebungen für MCP Server und Agent-Workflows: HTTP+SSE mit niedriger Latenz, native Python/Node-Runtime, SFTP/rsync für Notizen und Konfiguration — DSGVO-freundlicher als ein Heim-PC als Produktionshost. Welches Tool bauen Sie als Erstes? Mit Hello World starten Sie heute.