Ein MCP-Server stellt einer KI-Anwendung Werkzeuge mit klar beschriebenen Eingaben bereit. Für den Einstieg reicht eine lokale Funktion. Erst wenn Werkzeug und Client zusammen funktionieren, lohnt sich der Schritt zu einer entfernten Schnittstelle.
Diese Anleitung folgt der stabilen Version 2 des offiziellen TypeScript SDK und der Protokollrevision 2026-07-28, Stand 30. September 2026. Ältere Tutorials mit @modelcontextprotocol/sdk und Sitzungs-Transporten gehören zur SDK-v1-Linie. Die beiden Formen solltest du nicht mischen.
Projekt mit Node.js 20 oder neuer anlegen#
mkdir mein-mcp-server
cd mein-mcp-server
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server@2 zod@4 tsx
mkdir src
type=module ist erforderlich, weil das SDK ES-Module verwendet. Hier führt tsx TypeScript direkt aus. Deshalb gibt es keinen tsc-Build und keine vorausgesetzte dist/index.js. Wenn du JavaScript ausliefern willst, brauchst du zusätzlich eine passende Build-Konfiguration; tsc --init allein legt den gezeigten Ausgabepfad nicht fest.
Ein Werkzeug registrieren#
Speichere dies als src/index.ts:
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
serveStdio(() => {
const server = new McpServer({ name: "mein-server", version: "1.0.0" });
server.registerTool(
"add_numbers",
{
description: "Add two numbers and return their sum",
inputSchema: z.object({ a: z.number(), b: z.number() })
},
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }]
})
);
return server;
});
Das Schema validiert die beiden Zahlen. Die Beschreibung sagt dem Assistenten, wann das Werkzeug sinnvoll ist. serveStdio übernimmt die Verbindung über die Standard-Streams des Prozesses. Starte den Server zum Prüfen mit npx tsx src/index.ts; dass er auf Eingabe wartet und keinen Begrüßungstext ausgibt, ist normal.
Mit einem lokalen Client verbinden#
Für Claude Desktop liegt die lokale Konfiguration unter ~/Library/Application Support/Claude/claude_desktop_config.json auf macOS und %APPDATA%\Claude\claude_desktop_config.json auf Windows. Verwende absolute Pfade für das installierte tsx-Programm und deine Datei:
{
"mcpServers": {
"mein-server": {
"command": "/absolute/path/to/node_modules/.bin/tsx",
"args": ["/absolute/path/to/mein-mcp-server/src/index.ts"]
}
}
}
Auf Windows passe auch den Programmpfad an deine Installation an. Nach dem Neustart des Clients sollte add_numbers verfügbar sein. Bitte den Assistenten, mit diesem Werkzeug zwei Zahlen zu addieren, und prüfe das Ergebnis und den tatsächlich verwendeten Aufruf.
In Claude Code kannst du denselben lokalen Prozess registrieren:
claude mcp add mein-server -- /absolute/path/to/node_modules/.bin/tsx /absolute/path/to/mein-mcp-server/src/index.ts
Was vor dem Produktiveinsatz dazugehört#
Schreibe bei stdio keine Debug-Ausgaben auf stdout: Dort dürfen nur Protokollnachrichten stehen. Lokale Logs gehen auf stderr. Begrenze Eingaben, behandle erwartbare Fehler verständlich und gib Werkzeugfehler passend zurück. Externe Dienste brauchen Zeitlimits und gegebenenfalls Rate Limits.
Die Beispieladdition hat keine externen Abhängigkeiten und verändert keine Daten. Sobald ein Werkzeug Dateien schreibt oder eine fremde API verwendet, kommen echte Berechtigungen, Geheimnisverwaltung und eine Prüfung der Nebenwirkungen dazu. Ein lokaler Transport garantiert nicht, dass ein Server keine Daten ins Netz sendet.
Remote über HTTP bereitstellen#
Für einen gehosteten Server nutze die HTTP-Anleitung des SDK-v2. Übernimm dabei eine vollständige Integration für deine Laufzeit statt ein altes Sessions-Beispiel: Die Revision 2026-07-28 arbeitet mit Metadaten pro Anfrage; Protokollsessions und der separate GET-Stream gehören nicht zu dieser Revision.
Prüfe insbesondere Origin-Validierung, Anmeldung und Berechtigungen. Lokale HTTP-Tests sollten nur auf localhost lauschen. Ein erreichbarer Endpunkt allein ist keine sichere Produktionsintegration. Prüfe auch, welche Revision der gewünschte Client tatsächlich unterstützt.
Quellen: SDK-v2-Einstieg, MCP-Transporte, stdio, stdio gegen HTTP.
