Een MCP-server bouwen in TypeScript (SDK v2) | We.Inc
Bouw een werkende MCP-server met de officiële TypeScript SDK v2: installeren, een tool met een Zod-schema registreren, via stdio verbinden en testen in de MCP Inspector.
Installeer het officiële pakket @modelcontextprotocol/server en Zod, maak een McpServer met een naam en versie, registreer elke tool met registerTool, een beschrijving en een Zod-invoerschema, en verbind daarna een StdioServerTransport. Voer npx @modelcontextprotocol/inspector uit om uw tools met de hand aan te roepen voordat een AI-toepassing ze gebruikt.
De onderdelen die u nodig hebt
Onderdeel
Waar het vandaan komt
Wat het doet
McpServer
@modelcontextprotocol/server
Bevat uw tools en beantwoordt protocolverzoeken
registerTool
Methode op McpServer
Voegt één tool toe: naam, beschrijving, invoerschema, handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Communiceert met de host via standaardinvoer en -uitvoer
z.object(...)
zod/v4
Beschrijft en valideert de argumenten van de tool
Inspector
npx @modelcontextprotocol/inspector
Laat u tools met de hand opvragen en aanroepen
Vink elke stap af terwijl u bezig bent. De checklist onthoudt waar u bent en elke stap heeft precies het commando of bestand dat u nodig hebt. De uiteindelijke server doorzoekt een kleine lijst notities, genoeg om elk bewegend onderdeel te zien zonder database.
Maak een map, voeg de package.json hieronder toe en installeer de twee dependencies.
Plak server.ts en vervang de notes-array door uw eigen data of een API-aanroep.
Start de Inspector en laat hem wijzen naar het commando dat uw server uitvoert.
Vraag de tools op, roep notes_search aan met een woord en controleer de tekst die terugkomt.
Schrijf nooit naar stdout vanuit een stdio-server. Die stream vervoert protocolberichten, dus een verdwaalde console.log maakt ze stuk. Gebruik console.error, dat naar stderr gaat.
Houd elke tool klein en specifiek. Tussen twee tools genaamd notes_search en notes_create kan een model makkelijker kiezen dan bij één notes-tool met een modusschakelaar.
Valideer in de handler en in het schema als een tool geld, bestanden of gegevens van anderen raakt. Het schema controleert de vorm, niet de toestemming.
Zet de hoofdversie van de SDK vast in package.json. Versie 1 zat in een ander pakket, @modelcontextprotocol/sdk, dus oudere tutorials passen niet bij deze imports.
Veelgestelde vragen
Welk npm-pakket installeer ik?
Installeer voor SDK-versie 2 @modelcontextprotocol/server voor servers en @modelcontextprotocol/client voor clients. Het oudere v1-pakket, @modelcontextprotocol/sdk, staat op een v1.x-branch en krijgt nog minstens zes maanden na de release van v2 bug- en beveiligingsfixes.
Heb ik Zod nodig?
De README van v2 gebruikt Zod v4 voor invoerschema's en importeert het uit zod/v4, en vermeldt dat andere Standard Schema-libraries zoals Valibot en ArkType ook werken. Installeer wat u kiest naast de SDK.
Kan de server draaien op Bun of Deno?
Volgens de README van de SDK draait hij op Node.js, Bun en Deno. De Inspector is een aparte Node-tool en de README daarvan vraagt om Node 22.19.0 of nieuwer.
Hoe maak ik de server op afstand beschikbaar?
Vervang het stdio-transport door Streamable HTTP en host het proces ergens waar het bereikbaar is. Voeg authenticatie toe voordat u een tool openstelt die data wijzigt, want iedereen die de URL kan bereiken, kan verzoeken sturen.
Hoe weet ik dat een AI-toepassing mijn tool begrijpt?
Lees uw beschrijving en schema alsof u verder niets over het project weet. Als een buitenstaander niet kan zien wanneer de tool moet worden aangeroepen en wat er moet worden meegegeven, gaat een model ook gokken. De Inspector toont precies wat een host te zien krijgt.
Waarom eerst stdio
Een stdio-server is gewoon een programma dat de host start. Er is geen poort, geen hosting en geen login, en dat maakt het de snelste weg naar een werkende tool die u op uw eigen machine kunt testen.
Als de tools eenmaal goed werken, verandert de overstap naar Streamable HTTP de transportregel en de hosting, niet de toolcode. Die scheiding is de belangrijkste reden om bedrijfslogica in gewone functies te houden die de handlers aanroepen.
Het antwoord van de handler ontwerpen
Een handler geeft een object terug met een content-array. Tekstitems zijn het gangbare geval, en korte, specifieke tekst werkt het best: zeg wat er overeenkwam en hoeveel, in plaats van een hele set records te dumpen.
Als er niets overeenkomt, geef dan een zin terug die dat zegt. Een lege string laat het model raden of de aanroep mislukte of dat de zoekopdracht gewoon leeg was.
De complete server
Twee bestanden. Vervang de notes-array door wat uw server moet doorzoeken.
type module laat de ES-importsyntax direct draaien; het startscript gebruikt tsx, zodat u een buildstap overslaat.
Eén tool met een Zod-schema, een gewone zoekfunctie en een stdio-verbinding. Logging gaat naar stderr, zodat het nooit met protocolberichten vermengd raakt.
Testen met de Inspector
De Inspector heeft drie modi. De web-UI is de makkelijkste plek om te beginnen; de CLI-modus past bij scripts en CI.
Modi van de Inspector
Verbind in de web-UI met het commando dat uw server start (npx tsx server.ts) en open dan de lijst met tools.
Installeer de SDK, Zod en een TypeScript-runner
Schrijf server.ts met één tool
Start de server één keer om te controleren dat hij niet crasht
Open de Inspector en verbind met uw server
Vraag de tools op en roep notes_search met de hand aan