Ein MCP Server ist ein Programm, das KI-Modellen strukturierte Tools bereitstellt — über das standardisierte Model Context Protocol. Mit dem offiziellen TypeScript SDK lässt sich ein funktionsfähiger MCP Server in unter 30 Minuten bauen. Dieser Artikel zeigt jeden Schritt: vom Setup bis zum Deployment.
MCP (Model Context Protocol) hat sich seit November 2024 zum De-facto-Standard für KI-Tool-Integration entwickelt. Über 10.000 MCP Server existieren bereits. Aber die meisten Entwickler nutzen fertige Server — und verpassen dabei das Potenzial, eigene Tools genau für ihre Anforderungen zu bauen.
Was brauche ich um einen MCP Server zu bauen?#
Ein MCP Server benötigt drei Dinge: Node.js (ab Version 18), das offizielle MCP SDK und einen MCP-kompatiblen Client zum Testen (Claude Desktop, Claude Code oder Cursor).
Die Grundstruktur ist simpel:
mkdir mein-mcp-server && cd mein-mcp-server
npm init -y
npm install @modelcontextprotocol/server @modelcontextprotocol/node zod
npm install -D typescript @types/node
npx tsc --init
Das SDK bietet zwei Transport-Optionen: stdio (lokaler Server, liest von stdin/stdout) und Streamable HTTP (remote Server, läuft als Web-Service). Für den Einstieg empfehlen wir stdio — es funktioniert sofort ohne Netzwerk-Setup.
Wie definiere ich Tools im MCP-Schema?#
Tools sind das Herzstuck jedes MCP Servers. Ein Tool hat einen Namen, eine Beschreibung (die das KI-Modell liest um zu entscheiden ob es das Tool nutzen will) und ein Input-Schema mit Zod-Validierung.
import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/node";
import { z } from "zod";
const server = new McpServer({
name: "mein-server",
version: "1.0.0",
});
server.registerTool(
"wetter_abfragen",
{
description: "Aktuelle Wetterdaten für eine Stadt abrufen",
inputSchema: z.object({
stadt: z.string().describe("Name der Stadt"),
}),
},
async ({ stadt }) => {
const res = await fetch(
`https://wttr.in/${encodeURIComponent(stadt)}?format=j1`
);
const data = await res.json();
const temp = data.current_condition[0].temp_C;
return {
content: [{ type: "text", text: `${stadt}: ${temp}°C` }],
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Wichtig: Die Beschreibung des Tools entscheidet, ob die KI es aufruft. Schreiben Sie sie aus der Perspektive des Modells: "Aktuelle Wetterdaten für eine Stadt abrufen" ist besser als "Wetter-API-Wrapper".
Wie verbinde ich den Server mit Claude Desktop?#
Nach dem Build (npx tsc) muss der Server in der Claude Desktop Config registriert werden. Die Datei liegt unter:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mein-server": {
"command": "node",
"args": ["/pfad/zu/mein-mcp-server/dist/index.js"]
}
}
}
Starten Sie Claude Desktop neu. Im Chat erscheint ein Werkzeug-Symbol — Ihr Tool ist jetzt verfügbar. Testen Sie mit: "Wie ist das Wetter in Berlin?"
Für Claude Code geht es noch einfacher:
claude mcp add mein-server node /pfad/zu/dist/index.js
Welche Best Practices gelten für MCP Server in Produktion?#
Der Schritt vom Prototyp zur Produktion erfordert fünf Massnahmen:
-
Error Handling: MCP Tools dürfen nicht abstürzen. Fangen Sie jeden Fehler und geben Sie eine verständliche Fehlermeldung zurück. Die KI kann mit "API nicht erreichbar" arbeiten, mit einem Stack Trace nicht.
-
Input-Validierung: Zod validiert automatisch, aber definieren Sie enge Schemas.
z.string().max(100)stattz.string(). KI-Modelle senden manchmal unerwartete Eingaben. -
Timeouts: Externe API-Calls brauchen Timeouts.
AbortSignal.timeout(10_000)verhindert hängende Requests. -
Logging: Nutzen Sie
server.sendLoggingMessage()stattconsole.log. So landen Logs im MCP-Client und nicht im Transport-Stream. -
Rate Limiting: Wenn Ihr Server externe APIs nutzt, implementieren Sie serverseitiges Rate Limiting. KI-Modelle rufen Tools aggressiver auf als menschliche User.
Wie deploye ich einen MCP Server remote?#
Für remote Deployment wechseln Sie von stdio auf Streamable HTTP Transport. Das aktuelle SDK nutzt dafür NodeStreamableHTTPServerTransport:
import { createServer } from "node:http";
import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/server";
import {
NodeStreamableHTTPServerTransport,
} from "@modelcontextprotocol/node";
const server = new McpServer({
name: "mein-server",
version: "1.0.0",
});
// Tools hier registrieren (wie oben)
const transports = new Map<string, NodeStreamableHTTPServerTransport>();
createServer(async (req, res) => {
if (req.url === "/mcp" && req.method === "POST") {
const sessionId = req.headers["mcp-session-id"] as string | undefined;
if (sessionId && transports.has(sessionId)) {
await transports.get(sessionId)!.handleRequest(req, res);
return;
}
// Neue Session
const transport = new NodeStreamableHTTPServerTransport({
sessionIdGenerator: () => randomUUID(),
onsessioninitialized: (sid) => transports.set(sid, transport),
});
transport.onclose = () => {
if (transport.sessionId) transports.delete(transport.sessionId);
};
await server.connect(transport);
await transport.handleRequest(req, res);
}
}).listen(3100);
Clients verbinden sich dann per URL. In Claude Desktop:
{
"mcpServers": {
"mein-server": {
"url": "https://mein-server.example.com/mcp"
}
}
}
Sicherheit: Remote MCP Server brauchen Authentifizierung. Das Protokoll unterstützt OAuth 2.1 — oder Sie nutzen API Keys im Bearer Header. Ohne Auth ist Ihr Server öffentlich zugänglich.
Fazit#
Ein eigener MCP Server gibt Ihnen volle Kontrolle darüber, welche Tools Ihre KI nutzen kann. Die Einstiegshürde ist niedrig (ein npm-Package, eine Datei), das Potenzial ist hoch. Starten Sie mit einem einfachen Tool, testen Sie es in Claude Desktop, und erweitern Sie schrittweise.
Weiterführend: Was ist das MCP-Protokoll? | MCP Server Architektur im Detail | MCP Tools installieren — Tutorial
