Hoe Bouw Je Je Eerste MCP-Server: Een Praktische Gids

Inhoudsopgave

Bijgewerkt juni 2026.

TL;DR: MCP (Model Context Protocol) is hoe je Claude gestructureerde toegang geeft tot externe tools en data — databases, bestanden, API’s — zonder het contextvenster te overbelasten. De server is eenvoudiger dan het lijkt: installeer de SDK, definieer je tools als JSON schema, implementeer de handlers, verbind via stdio. In minder dan 30 minuten kan Claude je aangepaste tools aanroepen.

[Operatorperspectief] Ik verbind regelmatig nieuwe tools met mijn agents, en MCP is nu de standaardweg om dat netjes te doen. Zodra de server is gebouwd, kan elke compatibele client — Claude Desktop, Claude Code, elke app die de Anthropic SDK gebruikt — deze gebruiken zonder wijzigingen in de aanroepende code. Dat is de waarde: eenmalig bouwen, overal hergebruiken.

Wat MCP eigenlijk is

Het Model Context Protocol is een open protocol dat standaardiseert hoe AI-modellen verbinding maken met externe context en tools. Denk eraan als een USB-C-standaard voor AI-integraties: vóór dit protocol moest elke app die Claude een database wilde laten lezen of een API wilde laten aanroepen zijn eigen oplossing bedenken. Daarna bouw je één MCP-server en elke conforme host kan deze gebruiken.

MCP definieert drie dingen die een server kan aanbieden:

• Tools — functies die Claude kan aanroepen (een bestand lezen, een DB bevragen, een Slack-bericht sturen)
• Resources — data die Claude kan lezen (documenten, databaserijen, bestandsbomen)
• Prompts — herbruikbare prompttemplates die de host kan injecteren

Voor de meeste operatorgebruiksscenario’s bouw je toolservers. Resources en prompts komen later, zodra de basis werkt.

De architectuur is client-server, waarbij de client (Claude Desktop, Claude Code, je aangepaste app) alles beheert. De server is passief — hij luistert alleen naar toolaanroepverzoeken en geeft resultaten terug.

De drie onderdelen van elke MCP-server

Elke MCP-server die je bouwt heeft dezelfde structuur:

1. Het serverobject — declareert de naam, versie en mogelijkheden van je server (tools, resources, prompts)
2. Tooldefinities — een lijst van tools met namen, beschrijvingen en JSON-schema’s voor hun invoer
3. Verzoekhandlers — de functies die worden uitgevoerd wanneer Claude een tool aanroept

Dat is het. Geen database, geen HTTP-stack, geen auth-laag nodig om te starten. De minimale server heeft minder dan 30 regels TypeScript.

Vereisten (2 minuten)

• Node.js 18+ — controleer met node --version
• TypeScript 5+ (hieronder opgenomen als dev-afhankelijkheid)
• Een MCP-client om te testen — Claude Desktop is gratis en de eenvoudigste manier om je server in actie te zien

Er is geen Anthropic API-sleutel nodig om een MCP-server uit te voeren. De API-sleutel bevindt zich in de client (Claude Desktop), niet in je server.

Stap 1: Het project instellen (3 minuten)

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript tsx @types/node

Voeg toe aan package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

Maak tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "strict": true
  },
  "include": ["src/**/*"]
}

Stap 2: De minimale server schrijven (5 minuten)

Maak src/index.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Declareer welke tools deze server aanbiedt
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "Telt de woorden in een blok tekst.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "De tekst om woorden in te tellen",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// Verwerk toolaanroepen van de client
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `Woordtelling: ${count}` }],
    };
  }

  throw new Error(`Onbekende tool: ${name}`);
});

// Verbind via stdio — zo communiceert Claude Desktop met de server
const transport = new StdioServerTransport();
await server.connect(transport);

Dit is de volledige server. Het registreert één tool (get_word_count) en implementeert deze. De structuur is wat telt.

Stap 3: Bouwen en registreren in Claude Desktop (5 minuten)

Compileer TypeScript:

npm run build

Registreer het nu in het configuratiebestand van Claude Desktop.

Op macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Op Windows: %APPDATA%\Claude\claude_desktop_config.json

Als het bestand niet bestaat, maak het aan:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/absoluut/pad/naar/my-mcp-server/build/index.js"]
    }
  }
}

Gebruik het absolute pad. Herstart Claude Desktop na het opslaan. Je ziet een hamerpictogram (🔨) in het berichtinvoerveld — dat betekent dat Claude je tools heeft ontdekt.

Stap 4: Een nuttige tool bouwen

Woorden tellen is ter illustratie. Hier is een nuttigere tool: bestanden lezen uit een projectmap, wat ik gebruik voor context-injectie-agents die codebases, changelogs of configuratiebestanden samenvatten.

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

De logica is hetzelfde: definieer tools met precieze JSON-schema’s, implementeer de handlers, valideer invoer om path traversal te voorkomen en geef tekst terug aan de client.

De fouten die ik maakte (zodat jij ze niet maakt)

Het pad moet absoluut zijn. Relatieve paden in de Claude Desktop-configuratie worden niet opgelost zoals verwacht. Gebruik altijd het volledige pad /home/gebruiker/....

Stdio betekent geen console.log in je server. Claude Desktop communiceert met je server via stdin/stdout. Een console.log voor foutopsporing corrumpeert de JSON-RPC-stroom. Log naar stderr:

process.stderr.write(`Debug: ${message}\n`);

Herstart Claude Desktop na elke configuratiewijziging. MCP-servers worden bij het opstarten geladen. Een bewerkt configuratiebestand doet niets totdat je de app sluit en opnieuw opent.

Toolbeschrijvingen zijn het product. Claude beslist of het je tool aanroept op basis van het veld description. Een vage beschrijving betekent dat Claude niet weet wanneer het te gebruiken. Een precieze beschrijving betekent dat Claude het op het juiste moment gebruikt. Investeer meer tijd in beschrijvingen dan in implementatie.

Hoe ik MCP-servers in productie gebruik

Het stdio-patroon werkt uitstekend voor Claude Desktop en Claude Code (lokaal). Voor productie-agents — de 30+ die ik op Cloudflare Workers uitvoer — gebruik ik de tool-use API van de Anthropic SDK direct, omdat ik de flexibiliteit nodig heb om per stap naar Haiku vs Sonnet te routeren.

De patronen die ik daadwerkelijk gebruik:

1. Lokale dev-tooling — MCP-servers voor Claude Code die projectspecifieke tools blootstellen
2. Context-injectie — MCP-servers die relevante docs vooraf laden zonder handmatig kopiëren
3. Prototype-naar-API-brug — ik bouw eerst MCP (sneller om te itereren), dan migreer ik de logica naar SDK tool-use voor productie

Wat hierna te bouwen

Zodra de serverstructuur duidelijk is, zijn de nuttige tools degene die toegang hebben tot de externe context van Claude:

• Databaselezer — voert een alleen-lezen SQL-query uit en geeft resultaten terug als JSON
• Slack-lezer — haalt de laatste N berichten van een kanaal op
• GitHub-lezer — lijst open PR’s, leest een bestand bij een specifieke commit
• Interne API-wrapper — roept je eigen REST API aan met ingebouwde auth-headers

Veelgestelde vragen

Heb ik een Anthropic API-sleutel nodig om een MCP-server te bouwen?

Nee. Je MCP-server roept de Anthropic API niet aan. Het reageert alleen op toolaanroepverzoeken van de client. De API-sleutel bevindt zich in de client, niet in de server.

Kan mijn MCP-server externe API’s aanroepen?

Ja — de handler is gewoon asynchrone TypeScript-code. Haal een weer-API op, bevraag een database, schrijf naar een bestand. De server geeft niet om wat de handler intern doet.

Wat is het verschil tussen stdio- en HTTP-transport?

Stdio is voor lokale servers — dezelfde machine als Claude Desktop of Claude Code. HTTP met SSE is voor externe servers die je als webservice kunt deployen. Begin met stdio; het is eenvoudiger te debuggen.

Hoe weet Claude wanneer het mijn tool moet aanroepen?

Claude beslist op basis van het veld description van de tool en de conversatiecontext. Als Claude je tool blijft negeren, verfijn de beschrijving.