Einen MCP-Server in TypeScript bauen (SDK v2) | We.Inc
Baue einen funktionierenden MCP-Server mit dem offiziellen TypeScript SDK v2: installieren, ein Tool mit einem Zod-Schema registrieren, über stdio verbinden und im MCP Inspector testen.
Installiere das offizielle Paket @modelcontextprotocol/server und Zod, erstelle einen McpServer mit Name und Version, registriere jedes Tool mit registerTool, einer Beschreibung und einem Zod-Eingabeschema und verbinde dann einen StdioServerTransport. Führe npx @modelcontextprotocol/inspector aus, um deine Tools von Hand aufzurufen, bevor eine KI-Anwendung sie anfasst.
Die Bausteine, die du brauchst
Baustein
Woher er kommt
Was er macht
McpServer
@modelcontextprotocol/server
Hält deine Tools und beantwortet Protokollanfragen
registerTool
Methode von McpServer
Fügt ein Tool hinzu: Name, Beschreibung, Eingabeschema, Handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Spricht mit dem Host über Standardeingabe und Standardausgabe
z.object(...)
zod/v4
Beschreibt und validiert die Argumente des Tools
Inspector
npx @modelcontextprotocol/inspector
Lässt dich Tools von Hand auflisten und aufrufen
Hake jeden Schritt ab, sobald du ihn erledigt hast. Die Checkliste merkt sich, wo du bist, und zu jedem Schritt gibt es den genauen Befehl oder die Datei, die du brauchst. Der fertige Server durchsucht eine kleine Liste von Notizen, was reicht, um jedes bewegliche Teil ohne Datenbank zu sehen.
Erstelle einen Ordner, füge die unten gezeigte package.json hinzu und installiere die zwei Abhängigkeiten.
Füge server.ts ein und ersetze das notes-Array durch deine eigenen Daten oder einen API-Aufruf.
Starte den Inspector und gib ihm den Befehl, der deinen Server startet.
Liste die Tools auf, ruf notes_search mit einem Wort auf und prüfe den Text, der zurückkommt.
Schreib aus einem stdio-Server nie auf stdout. Dieser Stream transportiert Protokollnachrichten, ein verirrtes console.log beschädigt sie also. Nutze console.error, das auf stderr geht.
Halte jedes Tool klein und konkret. Zwischen zwei Tools namens notes_search und notes_create kann ein Modell leichter wählen als bei einem einzigen notes-Tool mit Modusschalter.
Validiere zusätzlich zum Schema auch im Handler, wenn ein Tool Geld, Dateien oder Daten anderer Leute berührt. Das Schema prüft die Form, nicht die Berechtigung.
Fixiere die Hauptversion des SDK in package.json. Version 1 lag in einem anderen Paket, @modelcontextprotocol/sdk, daher passen ältere Tutorials nicht zu diesen Imports.
Häufige Fragen
Welches npm-Paket installiere ich?
Für SDK-Version 2 installierst du @modelcontextprotocol/server für Server und @modelcontextprotocol/client für Clients. Das ältere v1-Paket, @modelcontextprotocol/sdk, lebt auf einem v1.x-Branch weiter und bekommt nach dem v2-Release noch mindestens sechs Monate lang Bug- und Sicherheitsfixes.
Brauche ich Zod?
Die README von v2 nutzt Zod v4 für Eingabeschemas und importiert es aus zod/v4. Sie sagt außerdem, dass auch andere Standard-Schema-Bibliotheken wie Valibot und ArkType funktionieren. Installiere die Bibliothek deiner Wahl zusammen mit dem SDK.
Kann der Server auf Bun oder Deno laufen?
Laut README des SDK läuft es auf Node.js, Bun und Deno. Der Inspector ist ein separates Node-Tool, und seine README verlangt Node 22.19.0 oder neuer.
Wie mache ich den Server aus der Ferne erreichbar?
Tausche den stdio-Transport gegen Streamable HTTP und hoste den Prozess an einem erreichbaren Ort. Ergänze eine Authentifizierung, bevor du ein Tool freigibst, das Daten ändert, denn jeder, der die URL erreicht, kann Anfragen senden.
Woher weiß ich, dass eine KI-Anwendung mein Tool versteht?
Lies deine Beschreibung und dein Schema so, als wüsstest du sonst nichts über das Projekt. Könnte ein Fremder nicht erkennen, wann das Tool aufzurufen ist und was zu übergeben ist, rät auch ein Modell. Der Inspector zeigt genau, was ein Host sehen wird.
Warum zuerst stdio
Ein stdio-Server ist einfach ein Programm, das der Host startet. Es gibt keinen Port, kein Hosting und keinen Login, deshalb ist das der schnellste Weg zu einem funktionierenden Tool, das du auf deinem eigenen Rechner testen kannst.
Sobald die Tools sich richtig verhalten, ändert der Umstieg auf Streamable HTTP nur die Transportzeile und das Hosting, nicht den Tool-Code. Diese Trennung ist der Hauptgrund, die Geschäftslogik in einfachen Funktionen zu halten, die die Handler aufrufen.
Die Antwort des Handlers gestalten
Ein Handler gibt ein Objekt mit einem content-Array zurück. Text-Einträge sind der Normalfall, und kurzer, konkreter Text funktioniert am besten: Sag, was gepasst hat und wie viele Treffer es gibt, statt einen ganzen Datensatz auszukippen.
Wenn nichts passt, gib einen Satz zurück, der das sagt. Ein leerer String lässt das Modell rätseln, ob der Aufruf fehlgeschlagen ist oder die Suche einfach leer war.
Der komplette Server
Zwei Dateien. Ersetze das notes-Array durch das, was dein Server durchsuchen soll.
type module lässt die ES-import-Syntax direkt laufen, das start-Skript nutzt tsx, damit du dir einen Build-Schritt sparst.
Ein Tool mit einem Zod-Schema, einer einfachen Suchfunktion und einer stdio-Verbindung. Logs gehen auf stderr, damit sie sich nie mit Protokollnachrichten vermischen.
Mit dem Inspector testen
Der Inspector hat drei Modi. Die Web-Oberfläche ist der einfachste Einstieg, der CLI-Modus eignet sich für Skripte und CI.
Modi des Inspectors
Verbinde dich in der Web-Oberfläche mit dem Befehl, der deinen Server startet (npx tsx server.ts), und öffne dann die Liste der Tools.
SDK, Zod und einen TypeScript-Runner installieren
server.ts mit einem Tool schreiben
Den Server einmal starten, um zu prüfen, dass er nicht abstürzt
Den Inspector öffnen und mit deinem Server verbinden
Tools auflisten und notes_search von Hand aufrufen