Claude Code MCP-configuratie: .mcp.json, scopes en troubleshooting

Het formaat van .mcp.json

Een projectbestand met één externe server en één lokale server ziet er zo uit:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Het veld type is verplicht zodra url aanwezig is. Een url zonder type wordt gemeld als een configuratiefout (de melding zegt dat u "type": "http", of sse of ws moet toevoegen), wat een oudere en veel minder duidelijke klacht over een ontbrekend command heeft vervangen. De waarde streamable-http wordt geaccepteerd als alias voor http. Een externe server die een vaste inlogsleutel nodig heeft, gebruikt een headers-object; een lokale server gebruikt command, args en env. De optionele timeout is een limiet per tool-aanroep, in milliseconden. WebSocket-servers kunnen alleen worden opgegeven in een bestand of via claude mcp add-json; de vlag --transport accepteert geen ws.

Het commando claude mcp add met --scope project schrijft dit bestand voor u, dus handmatig bewerken is alleen nodig voor velden die het commando niet aanbiedt, of wanneer u de wijziging liever beoordeelt in een pull request.

Geheimen buiten het bestand houden

Omdat .mcp.json bedoeld is om te worden gecommit, mogen er geen tokens rechtstreeks in worden getypt. Claude Code breidt omgevingsvariabelen uit in command, args, env, url en headers: ${VAR} neemt de waarde van de variabele over, en ${VAR:-default} valt terug op de standaardwaarde wanneer de variabele niet is ingesteld.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Een aangeroepen variabele die niet is ingesteld en geen standaardwaarde heeft, verhindert niet dat de server laadt; de letterlijke tekst ${API_KEY} wordt zo verstuurd, en claude mcp list drukt een waarschuwing af. Die waarschuwing is het eerste waar u naar moet kijken wanneer een server wel verbindt maar elke aanroep als niet-geautoriseerd wordt afgewezen.

Voor een server die OAuth ondersteunt, is er niets te verbergen: laat de invoer bestaan uit alleen type en url, en elke gebruiker meldt zich eenmalig aan vanuit /mcp. Het token wordt per gebruiker opgeslagen, buiten de repository, en wordt weer verwijderd door claude mcp remove.

Goedkeuring, voorrang en beheerde servers

De eerste keer dat Claude Code een server tegenkomt in de .mcp.json van een project, vraagt een interactieve sessie of die mag worden gebruikt; niet-interactieve runs (claude -p, de Agent SDK, cloudsessies) laden de server zonder te vragen. De keuze wordt per project onthouden; claude mcp reset-project-choices vergeet die weer, zodat u opnieuw kunt goedkeuren na een wijziging.

Wanneer eenzelfde naam op meerdere plekken is gedefinieerd, geldt de volgorde: lokale scope, dan projectscope, dan gebruikersscope, dan servers die plugins aanbieden, dan connectors vanuit claude.ai. De volledige winnende invoer wordt gebruikt. Organisaties kunnen een vaste serverlijst opleggen via een beheerd configuratiebestand of de instelling managedMcpServers (Claude Code 2.1.259 of hoger); die staan boven elke scope op gebruikersniveau, en een beheerd bestand dat exclusieve controle claimt, laat claude mcp add weigeren met een melding dat een bedrijfsconfiguratie actief is. Toestaan- en weigerlijsten (allowedMcpServers, deniedMcpServers) kunnen ook beperken welke URL's of commando's gebruikers mogen toevoegen, en een weigering wint altijd.

De statusuitvoer lezen

claude mcp list meldt elke server als verbonden, vereist authenticatie, kon niet verbinden, wacht op goedkeuring, geweigerd via disabledMcpjsonServers, of uitgeschakeld voor dit project. Een paar minder voor de hand liggende waarschuwingen die het afdrukt, zijn de moeite waard om te kennen: verborgen spaties aan het begin of einde van een waarde (een geplakt token dat eindigde met een regeleinde), dezelfde naam die in twee scopes naar een ander eindpunt wijst, en een handvol gereserveerde namen die u niet voor uw eigen servers mag gebruiken. WebSocket-servers verschijnen helemaal niet in de lijst; controleer ze met claude mcp get <name> of /mcp.

Veelvoorkomende storingen en hun oplossingen

1. Een externe server toont "needs authentication" of antwoordt met 401 of 403. Open /mcp, selecteer de server en rond de aanmelding in de browser af, of voer claude mcp login <name> uit. Gebruikt de server een statisch token, controleer dan de waarde van de header en de waarschuwing over een niet-uitgebreide variabele.
2. Een lokale server kan bij het opstarten niet verbinden. Voer het commando handmatig uit in dezelfde shell om de werkelijke foutmelding te zien; de gebruikelijke oorzaken zijn een ontbrekende runtime, een pakket dat nog geïnstalleerd moet worden, of een verplichte omgevingsvariabele. Traag startende servers lopen tegen de opstartlimiet aan, die MCP_TIMEOUT verhoogt in milliseconden, bijvoorbeeld MCP_TIMEOUT=10000 claude.
3. De server verbindt, maar een tool geeft een afgekapt resultaat terug. Tool-uitvoer is standaard beperkt tot 25.000 tokens, met een waarschuwing vanaf 10.000; MAX_MCP_OUTPUT_TOKENS verhoogt de limiet.
4. Tools lijken te ontbreken in het gesprek. Claude Code stelt tooldefinities uit tot ze nodig zijn om de context klein te houden, dus bij het begin worden alleen namen en serverinstructies geladen; de assistent vindt ze alsnog zodra een verzoek erbij past. Zet "alwaysLoad": true op een serverinvoer als u wilt dat de volledige definities er al vanaf de eerste beurt zijn.
5. Een externe server valt midden in een sessie weg. Claude Code probeert een weggevallen verbinding tot vijf keer opnieuw met oplopende vertraging, en een mislukte eerste HTTP-verbinding tot drie keer, maar niet bij authenticatiefouten en niet voor lokale servers, dus een authenticatiefout lost zichzelf niet op.

De configuratie testen tegen een live dienst

De snelste manier om de .mcp.json van een project te valideren, is een server waarvan u de antwoorden onafhankelijk kunt controleren. Met { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } gecommit en elke ontwikkelaar eenmaal aangemeld via /mcp, moet een verzoek als "voer een HTTP-controle uit op onze staging-URL vanuit Europa en Azië" terugkomen met echte statuscodes en responstijden vanaf de controlepunten van HostTracker, wat ofwel bewijst dat het bestand correct wordt gelezen, ofwel de fout terugbrengt tot de aanmelding. De bijbehorende handleiding, hoe u een MCP-server toevoegt aan Claude Code, behandelt de commandoregelroute en de scopes uitgebreider.