Claude Code MCP-server toevoegen (en in Claude Desktop): zo doe je het, stap voor stap

Voorbereiding

Wat heb je nodig om een MCP-server toe te voegen?

Een MCP-server is een klein programma of een webdienst die Claude toegang geeft tot een ander systeem, zoals een browser, je Notion-workspace of een database. Toevoegen is één commando of een paar klikken. Wat je vooraf regelt, bepaalt of het de eerste keer meteen werkt.

Waarom die projectmap ertoe doet

Zonder extra optie bewaart claude mcp add een server alleen voor jou en alleen voor de map waarin je het commando typt. Dat heet de local scope. Open je Claude Code daarna in een andere map, dan is de server er niet. Dat is geen fout maar een keuze van Anthropic: zo belandt een koppeling niet ongemerkt in al je projecten. Wil je hem overal, dan gebruik je straks --scope user.

Nog geen Claude Code?

Installeer het eerst via de Claude Code-installatiegids. Op Windows werkt claude mcp add in PowerShell en de Opdrachtprompt precies hetzelfde als op de Mac, volgens de officiële quickstart. Welk abonnement bij Claude Code hoort, lees je op Claude-abonnementen.

Route kiezen

Claude Code, een connector of een extensie: welke route kies je?

Dezelfde MCP-server kun je op drie plekken toevoegen. De vuistregel: draait het systeem op internet, gebruik dan een remote server of connector. Moet Claude bij iets op je eigen computer, gebruik dan een lokale server. De tabel helpt je kiezen.

Remote of lokaal, in één zin

Een remote server draait bij de leverancier en je praat ermee via een URL. Een lokale server start Claude op je eigen computer als programma, met jouw rechten. Let op: een connector die je in claude.ai of Claude Desktop toevoegt, maakt verbinding vanaf de servers van Anthropic, niet vanaf je eigen computer. Een systeem dat alleen op je kantoornetwerk bereikbaar is, krijg je zo dus niet gekoppeld. Meer achtergrond staat op MCP en connectors.

Voorbeeld 1

Voorbeeld 1: Playwright MCP toevoegen aan Claude Code (lokale server)

Playwright MCP geeft Claude een browser die hij kan openen, aanklikken en uitlezen. Het is een open-sourceproject van Microsoft, je hebt er geen account voor nodig, en Anthropic gebruikt het zelf als voorbeeld in de officiële quickstart. Ideaal als eerste lokale server, omdat je direct ziet wat Claude doet.

Wat de onderdelen van het commando betekenen

playwright is een naam die je zelf kiest; Claude Code gebruikt hem als label en in commando's zoals remove. De twee streepjes -- scheiden de opties van Claude Code van het commando dat de server start. Alles erachter gaat ongewijzigd naar de server. npx -y downloadt en start het pakket zonder te vragen. Je ziet geen --transport, want een lokale server gebruikt standaard stdio, de manier waarop Claude en het programma via de terminal met elkaar praten.

Waarom wij de vorm met twee streepjes aanraden

De README van Playwright noemt claude mcp add playwright npx @playwright/mcp@latest, zonder streepjes. Dat werkt meestal ook. Zodra je er een optie achter zet die met een streepje begint, zoals --browser firefox of --headless, probeert Claude Code die zelf te lezen en krijg je een onduidelijke fout. Met -- ertussen voorkom je dat. Het voorbeeld met --browser: claude mcp add playwright -- npx -y @playwright/mcp@latest --browser firefox.

Wat je met Playwright in het werk doet

Een concreet mkb-voorbeeld: een webbureau of webwinkel laat Claude na elke websitewijziging het contactformulier invullen en controleren of de bedankpagina verschijnt, of alle Nederlandse productpagina's laden. Dat soort klikwerk deed je eerst zelf. Playwright werkt met de toegankelijkheidsboom van een pagina, de opbouw die ook schermlezers gebruiken, en niet met schermafbeeldingen. Daardoor kan Claude knoppen en velden op naam vinden. Wil je Claude liever in je eigen, ingelogde browser laten werken, kijk dan naar Claude in Chrome.

Voorbeeld 2

Voorbeeld 2: een remote MCP-server met inlog toevoegen (Notion)

Veel diensten draaien hun MCP-server zelf en laten je inloggen via OAuth, het bekende scherm "deze app wil toegang tot je account". Je deelt dan geen wachtwoord of sleutel met Claude. Notion is een goed voorbeeld omdat het in veel mkb-teams als wiki of projectlijst dient. Voor Linear, Sentry of Atlassian werkt het precies zo, alleen met een andere URL.

Heb je Notion al in claude.ai gekoppeld? Sla dit dan over

Connectors die je op claude.ai of in Claude Desktop toevoegt, verschijnen automatisch in Claude Code als je daar met hetzelfde claude.ai-account bent ingelogd. Voeg je dezelfde server toch ook met claude mcp add toe, dan wint jouw eigen versie en toont /mcp de connector als verborgen. Twee keer dezelfde koppeling levert dus niets op behalve verwarring.

Wanneer een header in plaats van OAuth

Sommige servers werken met een vaste sleutel in plaats van een inlogscherm. Die geef je mee met --header, bijvoorbeeld voor GitHub: claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer JOUW_TOKEN". Notion biedt zo'n MCP-token alleen op Business en Enterprise, en alleen een workspace-eigenaar kan er een maken. Voor de meeste mensen is OAuth de veiligere keuze, omdat je de toegang per persoon kunt intrekken.

Claude Desktop

Claude Desktop MCP: dezelfde twee servers toevoegen zonder terminal

In Claude Desktop en op claude.ai heet een MCP-server een connector, en een lokale server die je installeert heet een extensie. Je klikt alles bij elkaar. Hieronder eerst Notion via de directory, dan Playwright via het configuratiebestand.

Het blok voor claude_desktop_config.json

Dit is de standaardconfiguratie uit de README van Playwright. Staat er al iets in je bestand, zet playwright dan als extra regel binnen mcpServers:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
Het bestand staat op de Mac in ~/Library/Application Support/Claude/ en op Windows in %APPDATA%\Claude\. Gebruik bij servers die een map nodig hebben altijd volledige paden, zoals /Users/jouwnaam/Documenten, nooit een kort pad.

Een extensie (.mcpb) installeren

Heb je van een leverancier of je IT-afdeling een bestand met de extensie .mcpb gekregen, dan heb je het configuratiebestand niet nodig. Ga naar Settings > Extensions (in sommige versies Settings > Desktop app en dan Manage naast Extensions), sleep het bestand op de pagina en klik Install. Voor de door Anthropic beoordeelde lijst klik je Browse extensions. Werkt je organisatie met een allowlist, dan zie je alleen wat de beheerder toestaat.

Op Team of Enterprise

Daar voegt een Owner een connector eerst toe voor de hele organisatie, via Organization settings > Connectors. Als lid zie je anders Request in plaats van een verbindknop. Daarna logt iedereen met zijn eigen account in, zodat Claude per persoon alleen ziet wat die persoon mag zien.

claude mcp add

claude mcp add: de opties, scopes en commando's die je echt gebruikt

Met deze tabel kun je elke andere server toevoegen, beheren en weer opruimen. Volledige naslag over prompts, resources en limieten staat op MCP in Claude Code en in Claude Code commands.

De drie scopes, en welke wint

local (standaard): alleen jij, alleen deze map, opgeslagen in ~/.claude.json. user: alleen jij, alle mappen, ook in ~/.claude.json. project: iedereen die de map uit Git haalt, opgeslagen in .mcp.json. Staat dezelfde naam op meer plekken, dan wint local, dan project, dan user, dan servers uit plugins en als laatste je claude.ai-connectors. De velden worden niet samengevoegd: de hele definitie van de winnaar telt. Een scope wijzigen gaat door de server te verwijderen en opnieuw toe te voegen.

Sleutels uit je repo houden met .mcp.json

In .mcp.json mag je verwijzen naar omgevingsvariabelen in plaats van een sleutel letterlijk op te schrijven. ${API_KEY} wordt de waarde van die variabele, ${VAR:-standaard} gebruikt een standaardwaarde als de variabele ontbreekt. Dat werkt in command, args, env, url en headers. Voorbeeld:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
}
}
}
Zet bij een server met een url altijd "type" erbij. Waarom: zonder type leest Claude Code het blok als een lokale server.

Waarom Claude Code om goedkeuring vraagt

Staat er een .mcp.json in een map die je net hebt binnengehaald, dan vraagt Claude Code eerst of je die servers vertrouwt. Tot dan toont claude mcp list ⏸ Pending approval. Dat is bewust: zo kan een gekloonde repository geen programma's op jouw computer starten zonder dat jij ja zegt. Lees het bestand dus voordat je goedkeurt.

Werkt het?

Werkt het? Zo controleer je je MCP-server in drie stappen

Een bevestiging na claude mcp add betekent alleen dat de instelling is opgeslagen, niet dat de server ook start. Controleer daarom altijd op drie niveaus.

De eerste prompt om te plakken

Plak dit in Claude Code of Claude Desktop zodra je server verbonden is:
Welke MCP-servers en tools heb je nu tot je beschikking? Noem per server de naam, of de tools alleen lezen of ook iets kunnen wijzigen, en één concrete taak die ik er vandaag mee kan doen. Voer nog niets uit.
Waarom deze prompt: je ziet in één antwoord of de koppeling er is, en je dwingt jezelf om naar de schrijfrechten te kijken voordat Claude iets doet. De laatste zin voorkomt dat Claude direct gaat proberen.

Kijk hoeveel ruimte je servers innemen

Typ /context in een Claude Code-sessie. Je ziet hoe je contextvenster is verdeeld en welke MCP-tools zijn uitgesteld (deferred) of al geladen. Doe dit één keer na het toevoegen en nog eens na een week, dan zie je of een server meer kost dan hij oplevert.

Problemen oplossen

MCP-server werkt niet: melding, oorzaak en oplossing

Begin altijd met claude mcp list of claude mcp get <naam>: sinds recente versies staat de foutdetail er direct bij. Zoek daarna je melding in de tabel.

Ons oordeel

Ons oordeel: welke MCP-servers je niet zomaar installeert

Een MCP-server toevoegen is makkelijk. Juist daarom installeren mensen er te veel, van makers die ze niet kennen, met meer rechten dan nodig. Dit is wat wij teams in onze trainingen meegeven.

Wanneer wel, wanneer niet

Wel: als je een taak hebt die je nu met kopiëren en plakken tussen Claude en een ander systeem doet, en het systeem een server van de leverancier zelf heeft. Niet: omdat een lijstje op internet "de tien beste MCP-servers" noemt. Een server zonder vaste taak kost elke sessie ruimte en vergroot het aantal deuren naar je data, zonder dat je er iets voor terugkrijgt.

Installeer niet zomaar: onbekende makers

Een lokale server is een programma dat met jouw rechten op je computer draait. Een remote server ziet alles wat Claude ernaar stuurt. Kies daarom bij voorkeur de server van de leverancier zelf (Notion, Atlassian, GitHub) of een groot, actief onderhouden project. Een losse GitHub-repository zonder releases, zonder duidelijke maker en met weinig activiteit installeer je niet op een werkcomputer. Ook in de directory geldt: Verified is volgens Anthropic geen beveiligingsaudit, en bij een Community-connector heeft Anthropic alleen gescreend, niet diepgaand gekeken. En de maker kan de tools na de beoordeling nog wijzigen.

Installeer niet zomaar: schrijfrechten op productie

Koppel nooit een server met je beheerdersaccount aan je boekhouding, CRM of productiedatabase om "even te proberen". Een connector mag namens jou alles wat jouw account mag. Begin met een account of sleutel die alleen mag lezen, en zet in Customize > Connectors per tool Needs approval of Blocked voor alles wat iets wijzigt of verstuurt. Kies Always allow alleen voor tools die niets kunnen kapotmaken. Pas als de antwoorden een week kloppen, geef je meer rechten.

De combinatie waar het misgaat: buiten-inhoud plus schrijfrechten

Servers die inhoud van buiten ophalen, zoals Playwright (webpagina's), een mailbox of een ticketsysteem, kunnen verborgen instructies binnenhalen. Dat heet prompt injection. Anthropic en de Playwright-makers waarschuwen er allebei voor; de README zegt letterlijk dat Playwright MCP geen beveiligingsgrens is. Het risico wordt pas echt als dezelfde sessie ook iets kan versturen of wijzigen. Draai een browserserver dus niet in een sessie waarin ook je CRM met schrijfrechten aan staat.

Contextkosten van te veel servers, en hoe je het checkt

Elke server laadt bij de start van elke sessie zijn toolnamen en instructies. Claude Code stelt de volledige tooldefinities standaard uit tot ze nodig zijn (tool search), dus tien servers zijn geen ramp meer. Wat wel snel oploopt, is de uitvoer: Claude Code waarschuwt bij meer dan 10.000 tokens per toolantwoord en kapt standaard af op 25.000. Een browserpagina of een grote databasequery haalt dat makkelijk. De makers van Playwright schrijven zelf dat hun CLI met skills zuiniger is dan de MCP-server voor codeeragents. Check het met /context en zet servers die je in dit project niet gebruikt uit via /mcp, of verwijder ze met claude mcp remove. Meer over verbruik op Claude Code limieten.

De fout die we beginners het vaakst zien maken

De server toevoegen in de ene map en Claude Code openen in een andere. Je krijgt dan "No MCP servers configured" en denkt dat de installatie mislukt is. De oplossing is één optie: gebruik --scope user voor servers die je overal wilt, en local alleen voor servers die bij één project horen. De tweede fout: een gekopieerd commando uit een oude tutorial met -s global. Die scope heet nu user.

Twee Nederlandse aandachtspunten

AVG: alles wat Claude via een server leest, gaat mee in het gesprek. Koppel je Notion met klantdossiers, dan stuur je persoonsgegevens naar Claude. Bij connectors via claude.ai of Claude Desktop loopt de verbinding ook via de servers van Anthropic. Leg dus vast welke koppelingen persoonsgegevens raken; zie privacy en zakelijk gebruik. Microsoft 365: veel Nederlandse teams werken in Outlook, Teams en SharePoint. Koppel die via de connector op claude.ai, niet via claude mcp add, en laat op Team of Enterprise de Owner dat centraal doen.

Versies vastzetten voor serieus gebruik

@latest in een npx-commando betekent dat je bij elke start de nieuwste versie draait, zonder te zien wat er veranderd is. Voor een test is dat prima. Gebruik je de server dagelijks of deel je hem via .mcp.json met je team, zet dan een vast versienummer, bijvoorbeeld @playwright/mcp@0.0.83, en werk bewust bij.

Wat nu?

Wat nu? Je volgende stap na je eerste MCP-server

Werkt je eerste server, kies dan één taak waarvoor je hem deze week drie keer gebruikt. Daarna weet je of hij mag blijven. Dit zijn logische vervolgstappen.

Verder met Claude Code

Werk je met code of een website, ga dan door met Claude Code en GitHub, Claude Code in VS Code of een website bouwen met Claude. Playwright komt bij die laatste goed van pas om je pagina's te testen. Wil je een kant-en-klare set van skills, agents en servers bekijken, lees dan eerst Everything Claude Code voordat je iets installeert.

Je notities of kennisbank koppelen

Werk je liever in markdown-bestanden dan in Notion, dan laat Claude met Obsidian zien hoe je je vault als tweede brein gebruikt, met Claude Code in de map of via een MCP-server.

Servers en werkwijze bundelen

Een plugin bundelt MCP-servers met skills en instructies, zodat een collega alles in één keer installeert. Dat is de volgende stap als je team steeds dezelfde set gebruikt.

Geen server voor jouw systeem?

Voor veel Nederlandse pakketten bestaat (nog) geen officiële server. Je kunt er zelf een maken; zo bouw je een MCP-server in Python. Wil je een betrouwbare koppeling met bijvoorbeeld je ERP of planningssysteem zonder het zelf te bouwen, dan bouwen we die in twee weken samen met je team in de Agent Sprint.