MCP Server von Grund auf: 2026 Schritt-für-Schritt-Anleitung für KI-Tool-Aufrufe

Ein LLM kann ohne „Hände und Füße" weder Datenbanken abfragen, APIs aufrufen noch lokale Notizen lesen. Das Model Context Protocol (MCP) standardisiert per JSON-RPC die Anbindung von KI-Clients an externe Fähigkeiten — 2026 zählt das Ökosystem über 13.000 Server; OpenAI, Google und Microsoft unterstützen MCP vollständig. Schmerzpunkt: Function Calling ist proprietär fragmentiert, Modellwechsel erzwingt Neubau. Ergebnis: Nach diesem Artikel entwickeln, debuggen und deployen Sie produktionsreife MCP Server eigenständig — inklusive DSGVO-konformer Sicherheitsarchitektur. Struktur: Protokoll → Umgebung → Hello World → Tools/Resources/Prompts → HTTP-Remote → Debug/Test → Docker → Wissensbasis-Projekt → Ökosystem.

1. Was ist MCP? Protokoll verstehen, dann coden

1.1 Entstehungsgeschichte

Tool-Calling durchlief drei Generationen: Function Calling (OpenAI-proprietär) → Plugins (ChatGPT-Ökosystem, rückläufig) → MCP (offener Standard). Anthropic open-sourced MCP im November 2024 — Motivation: Bei jedem neuen KI-Client musste die Tool-Integration neu geschrieben werden (N×M-Explosion). MCP löst standardisierte Kommunikation zwischen KI und externen Tools: einmal Server schreiben, Cursor, Claude Desktop und VS Code nutzen ihn. 2026 liegt die Governance bei AAIF unter der Linux Foundation.

1.2 Protokollarchitektur

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

Client: KI-Host (Claude Desktop, Cursor, Custom Agent). Server: Ihre Fähigkeitsquelle. Drei Kernfähigkeiten: Tools — vom Modell aufrufbare Funktionen (Suche, Berechnung, SQL); Resources — lesbare Daten (Dateien, Config, URLs); Prompts — vordefinierte Prompt-Vorlagen mit Parameterinjektion.

1.3 Kommunikationsmechanismus

Basis: JSON-RPC 2.0. Transport: stdio (lokaler Subprozess, null Netzwerk-Setup) und Streamable HTTP (Spezifikation 2025-06-18 ersetzt HTTP+SSE, ideal für Remote/Multi-Client). Lifecycle: Handshake → Capability-Negotiation (tools/list) → Request/Response → Shutdown. ⚠️ Im stdio-Modus keine Nicht-Protokoll-Logs auf stdout — sonst scheitert JSON-RPC-Parsing.

1.4 MCP vs. Alternativen

Dimension	MCP	OpenAI Function Calling	LangChain Tools
Standardisierung	Offener Protokollstandard	Herstellerproprietär	Framework-gebunden
Transport	stdio / Streamable HTTP	HTTP	HTTP
Cross-Model	Ja	Nein	Teilweise
Resources/Prompts	Nativ	Nein	Nein
Ökosystem	13.000+ Server (2026)	Reif	Reif

2. Entwicklungsumgebung vorbereiten

2.1 Sprachwahl

Python (Einsteiger): offizielles SDK mcp + FastMCP-Dekoratoren, minimaler Boilerplate. TypeScript (Frontend/Fullstack): @modelcontextprotocol/sdk + Zod-Validierung, npm-Downloads über 150 Mio. Dieser Artikel fokussiert Python, TypeScript als Referenz.

2.2 Setup

# Python
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

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

2.3 Projektstruktur

my-mcp-server/
├── server.py            # Haupteinstieg
├── tools/               # Tool-Module
│   ├── calculator.py
│   └── web_search.py
├── resources/           # Resource-Module
│   └── file_reader.py
├── prompts/             # Prompt-Vorlagen
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

2.4 Debug-Tools

1) MCP Inspector: npx @modelcontextprotocol/inspector python server.py, Browser-UI unter localhost:6274. 2) Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json. 3) Cursor: Settings → MCP → mcpServers. Details: MCP-Protokoll-Tiefenanalyse.

3. Erster MCP Server: Hello World

3.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}! Das ist Ihr erster MCP-Tool."

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

3.2 Starten und verifizieren

python server.py
# oder MCP Inspector
npx @modelcontextprotocol/inspector python server.py

3.3 Cursor / Claude Desktop anbinden

// claude_desktop_config.json oder Cursor MCP
{
  "mcpServers": {
    "my-first-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ Absolute Pfade für Python und Skript. Nach Neustart sollte say_hello im Tool-Kontext erscheinen.

4. Tools: KI-aufrufbare Funktionen

4.1 Grundstruktur

Funktionssignatur = Dokumentation: Typen und Docstring werden vom SDK zu JSON Schema für das LLM. Naming: lowercase_snake, semantisch (web_search statt ws). Fehlerbehandlung: strukturierte Fehlerstrings statt ungefangener Exceptions — Server-Crash vermeiden.

4.2 Parametertypen

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, gibt Ergebnisliste zurück"""
    return [{"title": "Beispiel", "url": "https://example.com"}]

4.3 Praxis: 5 nützliche Tools

Tool	Zweck	Implementierung
Rechner	Mathe-Ausdrücke	`eval` nur mit Sandbox oder `ast`
Datei-I/O	Lokale Dateien	Allowlist, Path-Traversal-Schutz (DSGVO-relevant)
HTTP	Externe APIs	`httpx` + 30s Timeout
DB-Query	Read-only SQL	Parametrisiert, kein DDL
Zeit	Zeitzone/Umrechnung	`zoneinfo` Stdlib

4.4 Asynchrone Tools

import httpx

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

4.5 Fehlerbehandlung — Best Practices

1) Strukturierte Fehler: {"error": "...", "code": "TIMEOUT"}. 2) Timeout: alle I/O max. 30s. 3) Autorisierung: Allowlist auf Tool-Ebene — nicht auf LLM-Disziplin vertrauen. 4) DSGVO: personenbezogene Daten in Tool-Responses minimieren und protokollieren.

5. Resources: Dynamische Inhalte für die KI

5.1 Resource vs. Tool

Resource = Datenlieferant (primär read-only), Tool = Aktion. URI-Schema: file://, http://, custom://.

5.2 Statisch vs. dynamisch

import json

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

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Nutzerprofil nach ID"""
    return json.dumps({"user_id": user_id, "name": "Demo"})

5.3 Ressourcentypen

Text (text/plain, application/json), Binär (Bild/PDF als base64), Streaming (Echtzeitdaten, Streamable HTTP).

5.4 Praxis: Dateisystem-Resource-Server

Verzeichnis listen, Dateien lesen, optional resources/subscribe. Produktion: Root-Verzeichnis strikt begrenzen — siehe mcp-server-filesystem Allowlist-Design. DSGVO: Zugriff auf personenbezogene Dateien auditieren.

6. Prompts: Wiederverwendbare Vorlagen

6.1 Was ist ein MCP Prompt?

Vordefinierte Prompt-Fragmente mit dynamischen Parametern — Team-Konsistenz und Wartbarkeit. Ergänzt Cursor Agent Skills: MCP Prompt = Protokollschicht, Skill = Betriebshandbuch.

6.2 Vorlage erstellen

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """Code-Review-Vorlage"""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"""Bitte prüfen Sie folgenden {language}-Code:
1. Qualität und Lesbarkeit
2. Bugs und Sicherheitslücken
3. Performance-Optimierung

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

6.3 Multi-Turn-Prompts

Templates mit user und assistant — z. B. Interview-Simulation oder Debug-Assistent mit Rückfragen.

7. Fortgeschritten: HTTP-Transport (Remote MCP Server)

7.1 stdio vs. Streamable HTTP

Merkmal	stdio	Streamable HTTP
Deployment	Lokal	Remote-Server
Latenz	<5 ms	50–200 ms (Netzwerk)
Multi-Client	Nein	Ja
Szenario	Lokale Tools, IDE	SaaS/Team/7×24

⚠️ HTTP+SSE ist seit 2025-06-18 deprecated — neue Projekte: Streamable HTTP.

7.2 HTTP-Transport implementieren

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server")

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

Produktion: uvicorn/gunicorn + Reverse Proxy. Serverless (Cloud Run/Lambda): stateless_http=True wegen Session-Verlust bei Cold Start.

7.3 Authentifizierung und Sicherheit

Bearer Token, API-Key-Middleware, CORS-Allowlist, Rate Limiting (100 req/min/IP). Entwicklung: 127.0.0.1 binden — kein ungeschütztes 0.0.0.0. 2026: über 30 MCP-CVEs, inkl. CVSS 9.6 RCE in mcp-remote. DSGVO: Verarbeitungsverzeichnis, Datenminimierung, EU-Rechenzentrum für personenbezogene Tool-Daten.

8. Debugging und Tests

8.1 MCP Inspector

UI: Tools listen → manuell aufrufen → JSON-RPC-Rohdaten → Timeout/Fehler simulieren. Effizienz vs. direktes LLM-Debugging: ca. 10×.

8.2 Unit-Tests

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 "4" in result.content[0].text

8.3 Häufige Fehler

Fehler	Ursache	Lösung
Tool fehlt in KI	Falscher Pfad	config.json absolute Pfade prüfen
JSON-Serialisierung	Nicht unterstützter Typ	str oder dict konvertieren
Timeout	Tool zu langsam	async + 30s Limit
Zugriff verweigert	Pfad eingeschränkt	Allowlist konfigurieren

9. Produktionsdeployment

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

9.2 Cloud-Deployment

Railway / Render: Ein-Klick, ca. $5–20/Monat. AWS Lambda / Cloud Run: Serverless. Eigener VPS: Nginx + Let's Encrypt + systemd/launchd. EU-Standort für DSGVO-konforme Verarbeitung empfohlen.

9.3 Monitoring

Strukturierte Logs (JSON Lines), Prometheus (mcp_tool_calls_total), Sentry, /health. P99-Latenz-Alarm: 5s.

9.4 Versionierung

MCP-Protokollversion im Handshake; Tools rückwärtskompatibel erweitern; capabilities-Negotiation nutzen.

10. Praxisprojekt: Persönliche Wissensbasis MCP Server

10.1 Anforderungen

KI soll lokale Markdown-Notizen durchsuchen, semantisch finden, erstellen/aktualisieren. In Cursor: „Was habe ich letzte Woche über MCP notiert?"

10.2 Tech-Stack

Komponente	Wahl	Begründung
Vektordatenbank	ChromaDB / Qdrant	Lokal, zero-ops
Embedding	text-embedding-3-small	1536 Dim., günstig
File-Watcher	watchfiles	Auto-Reindex bei Änderung

10.3 Kernmodule

Vier Module: index_notes, semantic_search, write_note, notes://{path} Resource. Indexierung ~1000 Notizen: 2–5 Min. (M4 Pro). DSGVO: Notizen können personenbezogene Daten enthalten — Zugriff protokollieren.

10.4 Demo

Cursor-Eingabe: „Was stand in meinen MCP-Deployment-Notizen letzte Woche?" → Agent ruft semantic_search(query="MCP Deployment", days=7) → 3 Treffer (Similarity 0,82–0,91) → LLM fasst mit Zitaten zusammen. Gesamte Notizbibliothek bleibt außerhalb des Context Window.

11. MCP-Ökosystem und Ausblick

11.1 Empfohlene Server

mcp-server-filesystem, mcp-server-github, mcp-server-brave-search, mcp-server-postgres, mcp-server-slack. Registry: 13.000+ Server.

11.2 Trends 2026

Vier Big-Tech-Vollunterstützung; MCP Marketplace; Enterprise OAuth 2.1 auf der Roadmap; Komplement zu Google A2A (MCP = vertikale Tool-Schicht, A2A = horizontale Agent-Orchestrierung).

11.3 Lernpfad

① modelcontextprotocol.io Spezifikation; ② ersten öffentlichen MCP Server veröffentlichen; ③ MCP + Agent erkunden; ④ Open Source (Python/TS SDK) beitragen.

12. Fünf-Schritte-Checkliste

Schritt 1 — FastMCP Hello World, Inspector-Check. Schritt 2 — 3 Business-Tools + 1 Resource. Schritt 3 — Cursor/Claude (absolute Pfade). Schritt 4 — Streamable HTTP Remote. Schritt 5 — Docker + Monitoring + Sicherheitsaudit (DSGVO).

13. Referenzwerte

Metrik	Wert
MCP-Server-Ökosystem (2026)	13.000+
Wachstum 18 Monate	7,8× (1.200 → 9.400+)
TS SDK Downloads	150 Mio.+
MCP-CVEs 2026	30+
Empfohlenes Tool-I/O-Timeout	30s
Wissensbasis-Index (1000 Stück)	2–5 Min. (M4 Pro)

14. Deep Dive: Von lokalem stdio zum Mac-Remote-Knoten

Ein KI-Ingenieur betrieb Cursor + 5 stdio-MCP-Server (filesystem, postgres, brave-search, Wissensbasis, Browser) auf einem MacBook Air. 24 GB Unified Memory: 19 GB dauerhaft belegt — Thermik, Throttling, Deckel zu = Disconnect. Migration: Cursor lokal; 5 Server per Streamable HTTP auf Mac mini (64 GB), launchd-Keepalive; Verbindung via url: http://node.macgpu.local:8000/mcp. Tool-Call P99: lokal 180 ms → remote 95 ms (kein Throttling) — stabiler.

Windows/Linux-VPS laufen MCP, aber für Xcode/ComfyUI/Final Cut parallele Grafik/Multimedia + KI-Toolchains bleibt macOS oft überlegen. Lokales stdio für Entwicklung; 7×24-Produktion auf Remote Apple-Silicon: Unified Memory für parallele Tool-Calls, Laptop nur Orchestrierung — DSGVO-freundliche EU-Standorte verfügbar.

Für stabiles, mietbares Hosting von MCP-Server-Clustern und Agent Gateways: MACGPU Remote-Mac-Knoten — 7×24, HTTP-Reverse-Proxy vorkonfiguriert, Unified Memory nicht von Subprozessen gesättigt. Von „läuft" zu „läuft stabil" — ein Knoten genügt.