Python oder TypeScript fuer einen MCP Server?

Python mit dem offiziellen mcp-Paket ist am schnellsten fuer Backend- und KI-Ingenieure ohne MCP-Erfahrung. TypeScript mit @modelcontextprotocol/sdk passt zu Frontend- und Full-Stack-Teams im Node-Oekosystem. Beide SDKs implementieren dasselbe JSON-RPC-Protokoll.

Wann STDIO vs. HTTP+SSE Transport?

STDIO fuer lokale Entwicklung mit Cursor oder Claude Desktop—null Netzwerk-Overhead und starke Prozessisolierung. HTTP+SSE oder streamable HTTP, wenn mehrere Clients, Remote-Teams oder SaaS-Deployment gemeinsamen Netzwerkzugriff brauchen.

Warum MCP Server auf Mac Cloud statt Linux VPS oder nur Docker?

Cursor und Claude Desktop Hosts erwarten native macOS-STDIO-Subprozesse und launchd 7x24-Betrieb. Linux VPS fehlt macOS-Host-Kompatibilitaet; Docker fuegt Abstraktion und Apple-Toolchain-Luecken hinzu. VPSMAC Mac-Cloud-Knoten bieten Bare-Metal-macOS mit SSH und launchd fuer produktive MCP-Workloads.

MCP Server von Null entwickeln: Kompletter Entwicklerleitfaden (2026)

Wenn Claude, GPT oder Cursor Ihre Datenbank abfragen, APIs aufrufen oder lokale Notizen durchsuchen sollen—jedes Modell aber einen anderen Adapter braucht—stehen Sie vor derselben N×M-Integrationswand, die MCP loesen soll. Dieser Praxisleitfaden richtet sich an Backend- und KI-Entwickler mit Python- oder TypeScript-Grundlagen. Am Ende bauen, debuggen und deployen Sie einen produktionsreifen MCP Server mit Tools, Resources, Prompts, HTTP-Transport, Wissensbasis-Projekt und fuenf-Schritte-Mac-Cloud-Runbook.

1. Einfuehrung: Warum KI externe Tools braucht

LLMs sind leistungsstarke Textmaschinen, aber blind fuer Ihre Live-Systeme: Trainings-Cutoffs blockieren Echtzeitdaten, und Modelle koennen ohne Tool Use keine Seiteneffekte ausfuehren. Sie wollen einen Assistenten, der Ihr Markdown-Vault liest, SQL ausfuehrt oder interne APIs anspricht—ohne bei jedem Wechsel von Claude zu GPT oder von Cursor zu einer anderen IDE Integrationen neu zu schreiben.

Drei Kernschmerzpunkte vor MCP

Fragmentierte Tool-Anbindung. OpenAI Function Calling, Claude Tool Use und LangChain Tools definieren Schemas unterschiedlich—N Modelle × M Tools = N×M Adapter.
Keine Laufzeit-Discovery. REST-Endpunkte stehen in statischen Docs; KI kann nicht tools/list aufrufen, um mid-session zu erfahren, was verfuegbar ist.
Lokale Host-Abhaengigkeit. Cursor und Claude Desktop starten STDIO-Subprozesse auf macOS; ein Linux VPS oder geschlossenes Laptop bricht die Kette.

Model Context Protocol (MCP) standardisiert, wie Hosts Tools entdecken und aufrufen, Resources lesen und Prompt-Templates ueber JSON-RPC 2.0 laden. Dieses Tutorial geht von Null zu einem deploybaren Server—nicht nur Theorie. Fuer das Protokoll-Level „warum MCP das HTTP der KI ist", siehe unseren MCP-Protokoll-Deep-Dive.

2. Was ist MCP? Protokoll vor Code

Anthropic hat MCP im November 2024 open-sourced. Es sitzt zwischen KI-Clients (Claude Desktop, Cursor, Custom Apps) und dem Server, den Sie bauen—mit drei Capability-Typen:

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (Sie bauen dies)   │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (Aktionen)   (Daten lesen)  (Templates)

Tools — aufrufbare Funktionen (Suche, Berechnung, SQL)
Resources — adressierbare read-only Daten via URI (file://, config://)
Prompts — parametrisierte Prompt-Templates, die der Host injizieren kann

Lebenszyklus: initialize-Handshake → Capability-Negotiation → Request/Response → graceful shutdown. Transport: STDIO (lokaler Subprozess) oder HTTP + SSE / streamable HTTP (remote).

MCP vs. Function Calling vs. LangChain Tools

Dimension	MCP	OpenAI Function Calling	LangChain Tools
Standardisierung	Offenes Protokoll	Vendor-spezifisch	Framework-gebunden
Transport	STDIO / HTTP	Nur HTTP	Nur HTTP
Cross-Model	Ja	Nein	Teilweise
Resources / Prompts	Nativ	Nicht unterstuetzt	Nicht unterstuetzt
Laufzeit-Discovery	`tools/list`	Statisches Schema	Statisches Schema

3. Umgebung einrichten

Sprache waehlen

Python (empfohlen fuer diesen Leitfaden): offizielles SDK mcp mit FastMCP-Decorators. TypeScript: @modelcontextprotocol/sdk fuer Node-native Teams.

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

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

Projektstruktur

my-mcp-server/
├── server.py            # Einstiegspunkt
├── tools/
│   ├── calculator.py
│   ├── files.py
│   ├── http_client.py
│   ├── database.py
│   └── datetime_tools.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

Debug-Tools

MCP Inspector — npx @modelcontextprotocol/inspector
Claude Desktop — claude_desktop_config.json
Cursor — .cursor/mcp.json

4. Hello World: Ihr erster MCP Server

from mcp.server.fastmcp import FastMCP

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

@mcp.tool()
def say_hello(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}! This is your first MCP tool."

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

Starten und inspizieren:

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

In Cursor einbinden (.cursor/mcp.json):

{
  "mcpServers": {
    "my-first-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {}
    }
  }
}

Cursor neu starten, MCP-Einstellungen oeffnen und pruefen, dass say_hello in der Tool-Liste erscheint.

5. Tools: Fuenf praktische Beispiele

Tools sind Aktionen. Funktionssignaturen plus Docstrings werden zu JSON Schema fuer das Modell. Pydantic-Modelle fuer komplexe Inputs.

Tool 1 — Rechner

import ast
import operator

@mcp.tool()
def calculate(expression: str) -> str:
    """Safely evaluate a math expression like '2 + 2 * 3'."""
    ops = {
        ast.Add: operator.add, ast.Sub: operator.sub,
        ast.Mult: operator.mul, ast.Div: operator.truediv,
    }
    def _eval(node):
        if isinstance(node, ast.Num): return node.n
        if isinstance(node, ast.BinOp):
            return ops[type(node.op)](_eval(node.left), _eval(node.right))
        raise ValueError("Unsupported expression")
    return str(_eval(ast.parse(expression, mode="eval").body))

Tool 2 — Datei lesen/schreiben

from pathlib import Path
ALLOWED = Path("/data/notes").resolve()

@mcp.tool()
def read_file(path: str) -> str:
    """Read a text file under the allowed directory."""
    target = (ALLOWED / path).resolve()
    if not str(target).startswith(str(ALLOWED)):
        raise PermissionError("Path outside allowed root")
    return target.read_text(encoding="utf-8")

@mcp.tool()
def write_file(path: str, content: str) -> str:
    """Write text to a file under the allowed directory."""
    target = (ALLOWED / path).resolve()
    if not str(target).startswith(str(ALLOWED)):
        raise PermissionError("Path outside allowed root")
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content, encoding="utf-8")
    return f"Wrote {len(content)} bytes to {path}"

Tool 3 — HTTP-Request (async)

import httpx

@mcp.tool()
async def fetch_url(url: str, timeout: int = 10) -> str:
    """GET a URL and return response text (truncated to 8 KB)."""
    async with httpx.AsyncClient(timeout=timeout) as client:
        r = await client.get(url)
        r.raise_for_status()
        return r.text[:8192]

Tool 4 — Datenbankabfrage

import sqlite3

@mcp.tool()
def query_sql(sql: str) -> list[dict]:
    """Run a read-only SELECT against the app SQLite database."""
    if not sql.strip().upper().startswith("SELECT"):
        raise ValueError("Only SELECT queries allowed")
    conn = sqlite3.connect("app.db")
    conn.row_factory = sqlite3.Row
    rows = conn.execute(sql).fetchall()
    conn.close()
    return [dict(r) for r in rows]

Tool 5 — Zeit und Zeitzone

from datetime import datetime
from zoneinfo import ZoneInfo

@mcp.tool()
def now_in_timezone(tz: str = "UTC") -> str:
    """Return current time in an IANA timezone (e.g. America/New_York)."""
    return datetime.now(ZoneInfo(tz)).isoformat()

Best Practices: JSON-serialisierbare Typen zurueckgeben; strukturierte Fehlerstrings statt nackter Stack Traces; Timeouts bei Netzwerk- und DB-Calls; Pfade und SQL validieren gegen Injection.

6. Resources: Dynamische Inhalte fuer KI

Resources liefern Daten; Tools fuehren Aktionen aus. MCP adressiert sie per URI.

import json

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """Return application configuration as JSON."""
    return json.dumps({"version": "1.0.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Return a user profile by ID."""
    user = db.lookup(user_id)  # your data layer
    return json.dumps(user)

Mime-Typen: text/plain, application/json oder binaer fuer PDFs/Bilder. Fuer einen Filesystem-Server Verzeichnislisten und Dateiinhalte als Resources exponieren, damit das Modell Kontext liest ohne State ueber Tools zu aendern.

7. Prompts: Wiederverwendbare Template-Bibliothek

Prompts buendeln Multi-Turn-Templates mit Parametern—nuetzlich fuer Code Review, Incident-Triage oder Interview-Vorbereitung.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """Structured code review template."""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"""Review this {language} code for:
1. Readability and structure
2. Bugs and security issues
3. Performance improvements

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

Hosts rufen prompts/list und prompts/get auf, um konsistente Anweisungen zu injizieren—weniger Prompt-Drift ueber Sessions.

8. HTTP-Transport: Remote MCP Server

Merkmal	STDIO	HTTP + SSE / streamable HTTP
Deployment	Lokaler Subprozess	Remote-Server
Latenz	Sehr niedrig	Netzwerkabhaengig
Multi-Client	Ein Host-Prozess	Viele Clients
Ideal fuer	Cursor, Claude Desktop	Team-SaaS, geteilte Tools

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server", host="0.0.0.0", port=8000)

# Auth-Middleware in Produktion:
# - Bearer-Token-Header-Validierung
# - API-Key pro Tenant
# - CORS-Allowlist fuer Web-Clients
# - Rate Limiting (z. B. 100 req/min)

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Nginx oder Cloud-Load-Balancer fuer TLS-Termination davor. Niemals einen unauthentifizierten MCP-HTTP-Endpoint ins oeffentliche Internet stellen.

9. Debuggen und testen

MCP Inspector Workflow

Start: npx @modelcontextprotocol/inspector python server.py
tools/list aufrufen und Schemas pruefen
Jedes Tool mit Edge-Case-Inputs testen
JSON-RPC Request/Response-Paare in der UI inspizieren

Automatisierter Test

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

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

Haeufige Fehler

Fehler	Ursache	Fix
Tool fehlt im Host	Falscher Pfad in mcp.json	Absolute Pfade; Host neu starten
JSON-Serialisierung fehlgeschlagen	Nicht serialisierbarer Return	str oder dict zurueckgeben
Timeout-Disconnect	Langsames sync Tool	Async machen; Timeout setzen
Permission denied	Pfad ausserhalb Allowlist	Erlaubte Roots konfigurieren

10. Produktions-Deployment

Fuenf-Schritte-Produktions-Runbook

Schritt 1 — Containerisieren

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
HEALTHCHECK CMD curl -f http://localhost:8000/health || exit 1
CMD ["python", "server.py"]

Schritt 2 — Transport und Authentifizierung

Streamable HTTP aktivieren; Bearer Token oder API Key bei jedem Request; CORS auf bekannte Host-Origins beschraenken.

Schritt 3 — Vor dem Ship testen

MCP Inspector plus pytest-Suite; tools/call p95-Latenz-Baselines dokumentieren.

Schritt 4 — Observability

Strukturierte JSON-Logs, Prometheus-Counter pro Tool-Name, Sentry fuer unhandled Exceptions, /health fuer Orchestratoren.

Schritt 5 — Auf dauerhafter Infrastruktur hosten

Fuer STDIO-Workflows mit Cursor launchd auf einem always-on Mac-Knoten mit CPU- und Memory-Limits. Fuer HTTP-Modus Railway, Render, Cloud Run oder Nginx auf VPS—mit TLS und Auth.

MCP-Protokollversion in initialize-Responses deklarieren und Tools versionieren, um bestehende Clients nicht zu brechen.

11. Projekt: Persoenliche Wissensbasis MCP Server

Ziel: Cursor soll „Was habe ich letzte Woche ueber MCP geschrieben?" beantworten, indem lokale Markdown-Notizen durchsucht werden.

Stack

Vector Store: ChromaDB oder Qdrant
Embeddings: text-embedding-3-small oder lokales Modell
File Watch: watchfiles zum Re-Index bei Save

Kern-Tools

@mcp.tool()
def index_notes(directory: str) -> str:
    """Scan Markdown files and rebuild the vector index."""
    count = indexer.rebuild(directory)
    return f"Indexed {count} documents"

@mcp.tool()
def semantic_search(query: str, top_k: int = 5) -> list[dict]:
    """Search notes by meaning; return title, path, and snippet."""
    return vector_store.search(query, k=top_k)

@mcp.tool()
def create_note(title: str, content: str) -> str:
    """Create a new Markdown note and index it."""
    path = vault.create(title, content)
    indexer.add(path)
    return str(path)

Vault-Dateien als Resources (note://{slug}) fuer read-only Preview. In Cursor natuerlichsprachige Fragen stellen; das Modell ruft semantic_search auf und zitiert Snippets aus dem Vault.

12. MCP-Oekosystem-Ausblick

Mitte 2026 unterstuetzt MCP Claude Desktop, Cursor, VS Code Copilot Extensions, OpenAI Responses API Tooling und einen wachsenden Marketplace. Referenz-Server zum Studieren:

mcp-server-filesystem — sandboxed Datei-Ops
mcp-server-github — Repos, PRs, Issues
mcp-server-brave-search — Websuche
mcp-server-postgres — SQL ueber MCP
mcp-server-slack — Team-Messaging

Enterprise-Adoption treibt Auth-Standards (OAuth 2.1, scoped API Keys) und auditierte Server-Registries. Naechste Schritte: Spec auf modelcontextprotocol.io lesen, Server auf GitHub veroeffentlichen, MCP mit Agent-Orchestrierungs-Frameworks kombinieren.

13. Harte Fakten zum Zitieren (2026-06-16)

Protokoll-Ursprung: MCP von Anthropic im November 2024 open-sourced; basiert auf JSON-RPC 2.0 mit STDIO- und HTTP-Transport.
Offizielle SDKs: Python (mcp) und TypeScript (@modelcontextprotocol/sdk) unter github.com/modelcontextprotocol.
Drei Primitive: Jeder Server exponiert Tools (Aktionen), Resources (read URIs) und Prompts (Templates)—zur Laufzeit via tools/list, resources/list, prompts/list discoverbar.
Inspector: Offizielle Debug-UI via npx @modelcontextprotocol/inspector; live JSON-RPC-Tracing ohne Host.

14. Fazit: Vom Tutorial zum produktionsreifen MCP

Sie haben den vollen Pfad: Protokoll-Mentalmodell, Python-SDK-Setup, fuenf Tools, Resources, Prompts, HTTP-Modus, Inspector-Tests, Docker-Packaging und Wissensbasis-Referenzprojekt. Alles auf einem lokalen Laptop funktioniert fuer Demos—aber Deckel-zu-Sleep killt STDIO-Sessions, Pfad- und Permission-Quirks multiplizieren sich im Team, und Linux VPS oder nur Docker koennen keine nativen Cursor/Claude-Desktop-Subprozesse oder Apple-Toolchain-Sidecars ohne Workarounds hosten.

Fuer stabile, auditierbare, 7×24 MCP Server, die Cursor und Claude Desktop zuverlaessig erreichen, deployen Sie auf einem dedizierten VPSMAC M4 Mac-Cloud-Knoten: Bare-Metal-macOS, launchd KeepAlive, SSH in Minuten, pinnbare Python-Umgebungen und Raum fuer HTTP-Gateways plus STDIO side-by-side. Das ist der produktionsreife 2026-Pfad—kontrollierbarer als auf dem Hauptrechner zu hoffen, er bleibt wach, und deutlich einfacher als macOS-Host-Workflows auf Linux VPS zu erzwingen.