MCP Server von Null entwickeln: Schritt für Schritt zur AI-Tool-Calling-Fähigkeit

Tool-Calling hat drei Generationen durchlaufen: Function Calling (herstellerspezifische Formate) → Plugins (plattformgebunden) → MCP (offener Protokollstandard). Anthropics Kernmotivation für MCP: Eine JSON-RPC-Spezifikation vereinheitlicht, wie AI-Clients externe Fähigkeiten entdecken, beschreiben und aufrufen — und beendet das N-Modelle-×-M-Tools-Integrationsproblem.

• Schmerzpunkt: Modelle fehlt Zugriff auf externe Tools und Echtzeitdaten — keine DB-Abfragen, API-Calls oder Dateioperationen.
• Szenario: Claude / GPT soll Datenbanken abfragen, REST-APIs aufrufen, lokale Markdown-Dateien lesen und schreiben — genau das liefert ein MCP Server.
• Ergebnisversprechen: Nach diesem Artikel entwickeln und deployen Sie eigenständig einen produktionsreifen MCP Server.

Architektonisch kommunizieren MCP Client (Claude Desktop, Cursor u. a.) und MCP Server (Ihr Code) bidirektional per JSON-RPC; der Server koppelt an externe Systeme:

• Tools: Von der KI aufrufbare Funktionen (Suche, Berechnung, DB-Abfrage)
• Resources: Von der KI lesbare Ressourcen (Dateien, URLs, Datenströme)
• Prompts: Vordefinierte Prompt-Vorlagen mit Parameter-Injektion

Die Kommunikation basiert auf JSON-RPC 2.0. Transportvarianten: stdio (lokaler Subprozess, minimale Latenz) und HTTP + SSE / Streamable HTTP (Remote-Service, mehrere Clients). Lebenszyklus: Initialisierung → Capability-Negotiation → Request/Response → Shutdown.

Weiterlesen: Warum MCP das HTTP der KI-Ära wird; offizielle Spezifikation unter modelcontextprotocol.io.

Python (empfohlen für Einsteiger): Offizielles SDK mcp, FastMCP-Dekoratoren sind schlank und zugänglich. TypeScript (empfohlen für Frontend / Full-Stack): Offizielles SDK @modelcontextprotocol/sdk. Dieser Artikel nutzt Python als Hauptpfad, TypeScript als Gegenüberstellung.

Python-Umgebung
python -m venv .venv
source .venv/bin/activate
pip install mcp

TypeScript-Umgebung (Vergleich)
npm init -y
npm install @modelcontextprotocol/sdk

Empfohlene Projektstruktur:

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

Debugging-Dreierpack:

• MCP Inspector: Offizielle Debug-UI zum visuellen Testen von Tools / Resources / Prompts
• Claude Desktop: claude_desktop_config.json bearbeiten für lokale Integration
• Cursor MCP-Konfiguration: Settings → MCP → stdio-Startbefehl hinzufügen

Mit FastMCP reichen zehn Zeilen für den ersten lauffähigen Server:

from mcp.server.fastmcp import FastMCP

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

@mcp.tool()
def say_hello(name: str) -> str:
    """Begrüßt die angegebene Person"""
    return f"Hello, {name}! Das ist dein erstes MCP-Tool."

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

Ausführung und Verifikation:

python server.py
Alternativ: MCP Inspector
npx @modelcontextprotocol/inspector python server.py

Cursor-Anbindung in sechs Schritten:

1. Python-Pfad ermitteln: In der venv which python — absoluten Pfad notieren.
2. Cursor MCP-Einstellungen öffnen: Settings → Features → MCP Servers.
3. stdio-Server hinzufügen: command = Python-Pfad, args = absoluter Pfad zu server.py.
4. Cursor neu starten: MCP-Konfiguration wirksam machen.
5. Tool-Liste prüfen: Im Agent-Modus prüfen, ob say_hello erscheint.
6. Aufruf auslösen: AI bitten, „mit say_hello JEXCLOUD zu begrüßen“ — korrekte Antwort bestätigen.

Claude Desktop analog: ~/Library/Application Support/Claude/claude_desktop_config.json bearbeiten und unter mcpServers dieselbe Konfiguration registrieren.

Tool-Vertrag: Die Funktionssignatur ist die Dokumentation — Parametertypen, Rückgabetyp und Docstring werden von MCP in JSON Schema für die KI übersetzt. Benennung in snake_case; Fehler als strukturierte Information statt nackter Exceptions zurückgeben.

Komplexe Parameter mit Pydantic modellieren:

from pydantic import BaseModel, Field

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

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

Fünf praxisnahe Tools als Übungs-Checkliste:

• Rechner: Sichere Auswertung mathematischer Ausdrücke (ast.literal_eval gegen Injection)
• Datei-Lese/Schreib: read / write nur in Whitelist-Verzeichnissen
• HTTP-Requests: GET / POST mit einheitlichem Timeout und Retry
• Datenbankabfrage: Read-only SQL + parametrisiert gegen Injection
• Zeit-Tools: Aktuelle Zeit, Zeitzonenkonvertierung, ISO-8601-Formatierung

IO-intensive Tools asynchron implementieren:

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Lädt Inhalt der angegebenen URL"""
    async with httpx.AsyncClient() as client:
        response = await client.get(url, timeout=30.0)
        return response.text

Fehlerbehandlung Best Practice: Timeouts setzen, Berechtigungsprüfung (Pfad-Whitelist / API Key), Rückgabe als {"error": "...", "code": "..."} für KI-Selbstkorrektur.

Unterschied Resource vs. Tool: Resource liefert Daten (read-only), Tool führt Aktionen aus (schreibend, mit Nebenwirkungen). Adressierung per URI-Schema: file://, http://, custom://.

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

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

Abgedeckte Ressourcentypen:

• Text: text/plain, application/json
• Binär: Bilder, PDF (Base64 oder Blob-URI)
• Streaming: Echtzeit-Logs, Marktdaten (Resource-Subscription)

Dateisystem-Resource-Server in der Praxis: Verzeichnis auflisten → Datei nach Pfad lesen → optional watchfiles für Änderungen und Resource-Update-Benachrichtigungen.

MCP Prompts sind vordefinierte Prompt-Fragmente, die AI-Clients direkt wiederverwenden können — mit dynamischer Parameter-Injektion für konsistente, wartbare Team-Prompts.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """Code-Review-Prompt-Vorlage"""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"Bitte prüfe den folgenden {language}-Code..."
            )
        )
    ]

Mehr-Runden-Vorlagen mischen user- und assistant-Rollen. Typische Szenarien: Interview-Simulation (assistant fragt, user antwortet), Debug-Assistent (assistant führt durch Fehlerschritte).

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)

Produktion erfordert zusätzlich: Bearer-Token-Authentifizierung, API-Key-Middleware, CORS-Whitelist, Rate Limiting (z. B. slowapi). Remote-Server eignen sich für geteilte DB-Abfragen, interne API-Gateways u. ä.

MCP Inspector-Workflow: Inspector starten → stdio-Befehl verbinden → tools/call in der UI testen → JSON-RPC Request/Response-Logs prüfen → Timeout- und Berechtigungs-Szenarien simulieren.

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"

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

Deployment-Optionen:

• Railway / Render: One-Click-Deploy, geeignet für persönliche Projekte
• AWS Lambda / Google Cloud Run: Serverless, nutzungsbasierte Abrechnung
• Eigener VPS: Nginx Reverse Proxy + TLS mit Bearer Token

Observability-Dreierpack: strukturierte Request-Logs, Prometheus-Metriken für Tool-Aufrufe, Sentry-Fehleralarme; /health für Health Checks. Versionsmanagement: MCP-Protokollversion deklarieren, Tool-Upgrades rückwärtskompatibel halten, Capability-Negotiation gegen Client-Abstürze nutzen.

• MCP Python SDK: github.com/modelcontextprotocol/python-sdk
• MCP TypeScript SDK: github.com/modelcontextprotocol/typescript-sdk
• MCP Inspector: github.com/modelcontextprotocol/inspector

Anforderung: KI soll lokale Markdown-Notizen durchsuchen, semantisch abfragen sowie Notizen anlegen und aktualisieren können.

Technologie-Stack:

• Vektordatenbank: ChromaDB oder Qdrant (leichtgewichtig lokal)
• Embedding-Modell: text-embedding-3-small (OpenAI) oder lokal nomic-embed-text
• Dateiüberwachung: watchfiles für inkrementellen Index-Rebuild

Kernmodule:

• index_notes-Tool: Notizverzeichnis scannen, Chunks embedden, in Vektor-DB schreiben
• semantic_search-Tool: query → top-k relevante Fragmente
• write_note-Tool: Markdown-Dateien erstellen / anhängen
• notes://{path}-Resource: Volltext einzelner Notiz per URI

Demonstration: In Cursor fragen „Was habe ich letzte Woche zu MCP notiert?“ → KI ruft semantic_search auf → liefert relevante Fragmente und synthetisiert die Antwort. Der kürzeste Pfad, private Wissenssysteme in Agent-Workflows einzubinden.

Empfohlene Community-Server:

• mcp-server-filesystem: Dateisystem-Operationen
• mcp-server-github: GitHub-Repository-Operationen
• mcp-server-brave-search: Websuche
• mcp-server-postgres: Datenbankabfragen
• mcp-server-slack: Slack-Nachrichten

Ökosystem-Trends 2026: Cursor, Claude Desktop, VS Code, OpenAI und Google Gemini unterstützen MCP nativ oder planen es; MCP Marketplace beschleunigt Server-Verteilung; Enterprise-Sicherheitsstandards (OAuth 2.1, Audit-Logs) stehen auf der Roadmap.

Nächster Lernpfad: MCP-Spezifikation vertiefen → ersten öffentlichen Server veröffentlichen → MCP + Agent-Orchestrierung erkunden → PRs ans Open-Source-Ökosystem.

• Protokollversion: Erstveröffentlichung 2024-11-05; ab 2025 empfiehlt Streamable HTTP reines SSE für Remote-Transport
• Ökosystemgröße: Stand 2026 über 10.000 Community-MCP-Server
• SDK-Pflege: Anthropic Open Source + Linux Foundation AAIF; Python / TypeScript offizielle SDKs mit wöchentlichen Updates

MCP ist das Standardprotokoll für AI-Tooling — wer MCP-Server entwickeln kann, ermöglicht jedem LLM den Zugriff auf eigene Geschäftssysteme. Welches Tool würden Sie als Nächstes kapseln? Teilen Sie Ihr Szenario in den Kommentaren.

Die versteckten Kosten produktionsreifer MCP Server liegen in der Host-Stabilität: Laptop zuklappen beendet den STDIO-Subprozess; heimisches Breitband unterbricht HTTP-Long-Polling; Shared VPS ohne macOS-Sandbox und TCC-Berechtigungen. Für 24/7-Wissensbasis-Indexierung, Remote-HTTP-MCP oder Cursor-Agent-CI liefert JEXCLOUD Multi-Region Bare-Metal Mac dedizierte Apple Silicon, feste öffentliche IPs, 120-Sekunden-Bereitstellung und monatliche flexible Laufzeiten — produktionsreifer als „lokal zusammenbasteln + ständiges Reconnect“. Knoten und Preise: JEXCLOUD Preisseite; Deployment-Fragen: Hilfezentrum.