De veruit meest voorkomende oorzaak van "mijn assistent ziet mijn gegevens niet"
is geen kapotte server. Het is een client die nooit opnieuw is gestart nadat de
configuratie veranderde. De meeste MCP-clients lezen hun configuratie bij het
opstarten en daarna nooit meer, dus een bestand dat u bewerkte terwijl de app
openstond, is een bestand dat de app niet gelezen heeft. Sluit hem volledig af —
op macOS blijft het proces draaien als u alleen het venster sluit — en open hem
opnieuw. Voer in Claude Code /mcp uit in plaats van de terminal te herstarten.
Helpt dat niet, dan is de nuttige vervolgvraag niet "welke client gebruik ik" maar "wat gebeurt er precies". Een ontbrekende server, een server die verbinding maakt maar geen tools aanbiedt, tools die niets teruggeven en tools die alleen falen zodra ze iets willen wijzigen zijn vier verschillende storingen met vier verschillende oplossingen — en de oplossing hangt nauwelijks af van welke app u draait. Elk detail hier is op 14 augustus 2026 gecontroleerd in de documentatie van de leveranciers.
Kijk voordat u iets wijzigt naar wat de client al weet. Elke client heeft precies één plek die antwoord geeft op "heeft deze server verbinding gemaakt", en gokken vanuit het chatvenster is hoe mensen een uur besteden aan een probleem dat dat scherm in een seconde benoemt.
| Client | Waar u kijkt | Hoe een gezonde server eruitziet |
|---|---|---|
| Claude Code | claude mcp list of het /mcp-paneel |
✔ Connected |
| Claude Desktop | plus-icoon in het chatveld → Connectors | de server staat er met zijn tools |
| Cursor | Output-paneel (Cmd+Shift+U) → MCP Logs |
initialisatie, geen verbindingsfouten |
| VS Code | MCP: List Servers in de Command Palette | de server start, het Show Output-logboek is schoon |
| Zed | Settings → AI → MCP Servers | groene stip, tooltip Server is active |
Claude Code is hiervan de meest informatieve. claude mcp list drukt naast elke
server een gezondheidsstatus af — ✔ Connected, ! Needs authentication,
✘ Failed to connect, ⏸ Pending approval — en zet het detail van de storing
achter diezelfde regel; claude mcp get <name> toont hetzelfde op een
Issue:-regel, inclusief de fouttekst die de server zelf teruggaf.
Toont het statusscherm uw server helemaal niet, dan leest de client de regel niet die u geschreven hebt. Drie oorzaken dekken vrijwel alles.
Het bestand is geen geldige JSON. Eén komma te veel of één ontbrekende accolade en de client negeert het hele bestand — niet alleen de kapotte regel — meestal zonder dat te melden. Plak het bestand in een willekeurige JSON-validator voordat u iets anders verdenkt.
U hebt een ander bestand bewerkt dan de client leest. Bijna elke client heeft
zowel een persoonlijke als een projectgebonden configuratie, en de verkeerde
bewerken levert precies dit symptoom op. Cursor leest ~/.cursor/mcp.json
globaal en .cursor/mcp.json binnen een project; VS Code leest .vscode/mcp.json
in een werkruimte en een mcp.json in het gebruikersprofiel, die u opent met
MCP: Open User Configuration. Claude Code kent drie bereiken — lokaal en
gebruiker in ~/.claude.json, project in een .mcp.json in de hoofdmap van de
repository — en staat een naam in meer dan één bereik, dan wint lokaal van
project, en project van gebruiker. De hele regel komt uit het winnende bereik;
velden worden niet samengevoegd.
De sleutelnaam klopt niet voor die client. De sleutel op het hoogste niveau is
in VS Code servers, in Zed context_servers, en bij alle anderen mcpServers.
Een geplakt mcpServers-blok in VS Code is geen fout die de editor meldt — het is
simpelweg een sleutel die hij niet leest. Client voor client staat dat in
waar de MCP-configuratie staat.
Eén geval lijkt op een ontbrekende server maar is het niet: in Claude Code blijft
een projectgebonden server op ⏸ Pending approval staan totdat u claude
interactief in die map draait en hem goedkeurt, en goedkeuringen die in de
repository zijn vastgelegd worden genegeerd zolang u de werkruimte niet vertrouwt.
Als er niets in de configuratie is veranderd en de server toch geen verbinding
meer maakt, staat er meestal nog een absoluut pad in naar een programma dat er
niet meer is. Een app die in een andere map is bijgewerkt, hernoemd of uit
Programma's verplaatst, breekt het pad terwijl de JSON er nog goed uitziet, en
niets in de foutmelding van de client wijst op die verhuizing. Leg de waarde van
command eerst naast de werkelijkheid:
ls -l "/absolute/path/from/your/config"
Dezelfde soort storing treft servers die via een versiebeheerder starten. Is
command gelijk aan node, npx, python of uv en komt uw runtime uit nvm,
pyenv of asdf, dan bestaat het pad wel in uw terminal en niet voor de client,
omdat de client geen login-shell start. Vervang de kale naam door het absolute
pad — which node geeft het u — of laat command rechtstreeks naar het binaire
bestand wijzen.
Een groene status met een lege toollijst betekent dat de handshake is gelukt en
dat tools/list niets bruikbaars teruggaf. Twee dingen veroorzaken dat.
Het eerste is een server die werkelijk een lege set tools meldt, wat u buiten de client kunt bevestigen met de MCP Inspector — de referentie-testinterface die rechtstreeks verbinding maakt met een stdio- of Streamable HTTP-server en opsomt wat die publiceert. Ziet de Inspector wel tools en uw client niet, dan zit de fout in de configuratie van de client.
Het tweede is een toolplafond. VS Code beperkt één chatverzoek tot 128 ingeschakelde tools en weigert het verzoek zodra het totaal daarboven komt — een grens die een volle machine sneller haalt dan u zou denken; met de knop Configure Tools in de Chat-weergave zet u servers uit om er weer onder te komen. Cursor laat u afzonderlijke servers uitschakelen via het paneel Customize in de zijbalk, en een uitgeschakelde server laadt niet en verschijnt niet in de chat — de moeite waard om als eerste te controleren, want een schakelaar die iemand vorige maand omzette, ziet er precies zo uit als een server die niet kon starten.
De tools staan in de lijst, de assistent roept ze aan, en de resultaten zijn leeg. Het transport is hier in orde; de vraag gaat over gegevens, niet over configuratie. Controleer of de bibliotheek die de server leest dezelfde is die u in gedachten hebt — het juiste account, het juiste apparaat, en materiaal dat ook echt naar deze machine is gesynchroniseerd in plaats van alleen op een andere te staan. Kijk daarna in het logboek van de client naar de argumenten van de aanroep: een assistent die een datumbereik of een filter heeft geraden, kan een leeg resultaat opleveren uit een volstrekt gezonde bibliotheek.
Slagen zoekopdrachten wel, maar mislukt elke poging om iets te hernoemen, te taggen of bij te werken, dan is dit geen transportprobleem. Servers splitsen zich vaak in tools die lezen en tools die gegevens wijzigen, en die wijzigende helft draagt vaak een extra eis: een draaiende applicatie, een geauthenticeerde sessie, een recht dat de client niet heeft gekregen. Twee oorzaken aan de clientkant sluit u het beste als eerste uit. Tools die gegevens wijzigen zijn als zodanig aangemerkt, dus vraagt de client toestemming voordat hij ze uitvoert — en een verzoek dat u wegklikte, leest in het transcript als een mislukking. En een server die met een alleen-lezenvlag is gestart, publiceert die tools helemaal niet: dat is een configuratiekeuze, geen storing.
Dit is een fout van de server en niet van u, maar het loont hem te herkennen
omdat de foutmelding verwarrend is. Via stdio eist het protocol dat de
standaarduitvoer niets anders dan JSON-RPC-berichten bevat, dus een server die
een versiebanner, een "opstarten"-regel of een gekleurd logboek naar stdout
schrijft, beschadigt de stroom, en de client faalt met een parseerfout die de
eerste tekens van het gedrukte citeert —
Unexpected token 'S', "Starting s"... is not valid JSON. De oplossing ligt bij
de auteur van de server: logregels horen naar stderr, dat de host toch al
vastlegt.
De omgeving is de andere valkuil bij het opstarten. Een stdio-server erft slechts
een beperkte, platformafhankelijke set omgevingsvariabelen — niet uw shellprofiel
— en zijn werkmap kan ongedefinieerd zijn, feitelijk / op macOS. Geef wat de
server nodig heeft mee via de sleutel env in zijn configuratieregel, en houd
elk pad absoluut.
command bestaat, als absoluut pad.Van boven af werken kost een minuut. Bij stap zeven beginnen is hoe een probleem van vijf seconden een middag wordt.
Speak-Y levert zijn MCP-server mee in de macOS-app, dus verschillende van de
bovenstaande storingen kunnen hem niet overkomen: er is geen npm-pakket te
installeren, geen runtime die via nvm gevonden moet worden en geen token dat kan
verlopen. Wat wel kan gebeuren is het verouderde pad, en de app repareert dat
zelf. Bij het starten controleert hij de configuraties van Claude Code, Claude
Desktop en Cursor en herschrijft hij de waarde van command waar die naar een
oude locatie van de app wijst — alleen voor regels die echt van hem zijn, herkend
aan zijn eigen binaire bestand en het argument --mcp, zodat een andere server
die toevallig dezelfde naam draagt met rust wordt gelaten. Moet het met de hand,
dan toont Instellingen → Integraties naast elke herkende client
Opnieuw installeren; herstart daarna de client, of voer /mcp uit in Claude
Code.
De scheiding tussen lezen en wijzigen is het andere symptoom dat het herkennen
waard is. Opnames doorzoeken en transcripten, samenvattingen en actiepunten lezen
werkt rechtstreeks tegen de bibliotheek op deze machine en vereist verder niets
dat draait. De tools die ordenen — tags, titels, sprekersnamen, opnieuw
transcriberen, publiceren in een teamkanaal — lopen via de draaiende
app, dus met Speak-Y afgesloten mislukken ze terwijl zoeken gewoon blijft werken.
Die asymmetrie is op zichzelf al een diagnose: werkt lezen wel en wijzigen niet,
start dan de app in plaats van een configuratie te bewerken. --read-only
toevoegen aan de argumenten van de server haalt de wijzigende tools volledig uit
het zicht van de client — bedoeld gedrag, geen mankement. En lege resultaten van
een gezonde server betekenen meestal dat de opname nog op een ander apparaat
staat: de server leest deze schijf en haalt de rest niet op.
Bent u aan het instellen in plaats van aan het repareren, dan zijn de handleidingen per client nuttiger dan deze pagina: Claude Desktop en Claude Code stap voor stap, en VS Code, Zed en Devin Desktop voor de editors waarvan de configuratievorm van die van alle anderen afwijkt.
De meeste clients lezen hun MCP-configuratie alleen bij het opstarten, dus een configuratie die u schreef terwijl de client draaide, is nog niet geladen. Sluit de app volledig af en open hem opnieuw — op macOS is het venster sluiten niet genoeg — en voer in Claude Code /mcp uit in plaats van de terminal te herstarten.
Elke client heeft één plek die dat beantwoordt. Claude Code: claude mcp list, dat ✔ Connected, ! Needs authentication of ✘ Failed to connect naast elke server afdrukt. Claude Desktop: het plus-icoon in het chatveld, dan Connectors. VS Code: MCP: List Servers uit de Command Palette. Cursor: het Output-paneel met MCP Logs geselecteerd. Zed: Settings → AI → MCP Servers, waar een groene stip Server is active meldt.
In ~/Library/Logs/Claude op macOS en in %APPDATA%\Claude\logs op Windows. Volg ze live met tail -n 20 -F ~/Library/Logs/Claude/mcp*.log. Het bestand mcp.log bevat de algemene verbindingsgebeurtenissen en mcp-server-NAAM.log bevat wat die specifieke server naar stderr heeft geschreven.
De client start het proces zelf, niet via uw login-shell. Hij erft niet uw volledige PATH maar slechts een beperkte, platformafhankelijke set omgevingsvariabelen, en zijn werkmap kan ongedefinieerd zijn. Gebruik een absoluut pad voor command, absolute paden in de argumenten, en geef benodigde variabelen expliciet mee via de sleutel env.
Bijna altijd het absolute pad in de MCP-configuratie, dat naar de oude locatie van de app wijst. Opnieuw installeren in een andere map, de app hernoemen of hem uit Programma's verplaatsen breekt het pad terwijl de configuratie nog steeds klopt op het oog. Voer de installatie met één klik van die client opnieuw uit, zodat het pad wordt herschreven.