Deel C · Module 03
Verbinden: MCP
Hoe krijgt de agent nieuwe handen?
Leerdoelen
Na deze module kun je:
- de berichten tussen model, Claude Code en een MCP-server in volgorde tekenen, en aanwijzen waar de toestemmingscheck en de echte API-call zitten;
- een MCP-server toevoegen in de juiste scope (local, project, user) en voorspellen hoe hij heet in permissieregels en hook-matchers;
- uitleggen hoe tool poisoning werkt, en ten minste drie verdedigingen noemen die niet van het model afhangen.
Voorkennis-check
Twee vragen over tool use en hooks. Fout? Lees B2 Tool use en C2 Hooks & permissies eerst terug.
Waar zitten we?
MCP hoort bij laag 4, de harness. Claude Code is de host: hij praat met de servers, zet hun tools in de request (laag 2) en voert de tool calls uit die het model in de loop (laag 3) aanvraagt. Het model praat nooit rechtstreeks met een server.
De stof in drie lagen
Kern ± 5 min lezen, daarna drie scenario's doorlopen
In B2 definieerde je zelf tools: een naam, een description, een JSON Schema, plus code die de tool uitvoert. Dat werkt, maar elke integratie (GitHub, Jira, Postgres, Sentry) zou je dan per agent opnieuw moeten bouwen. Het Model Context Protocol (MCP) standaardiseert dat: één server per systeem, bruikbaar in elke host die MCP spreekt (Claude Code, Claude Desktop, VS Code en andere).
Wat MCP is
- Een protocol (JSON-RPC 2.0) tussen host en server
- De server levert tools, resources en prompts
- De server voert de tool uit, met zijn eigen credentials
- Lokaal (stdio-subproces) of remote (HTTP)
Wat MCP níét is
- Geen nieuwe modelcapaciteit: voor het model is het gewoon tool use
- Geen beleid: wie wat mag, regel je met permissies en hooks
- Geen kennis: hoe je de tools goed gebruikt, leg je vast in een skill
- Geen garantie dat een server te vertrouwen is
Doorloop de berichten hieronder. Begin met het normale verloop en let op twee dingen: het model ziet alleen een tool_use-blok, en jouw toestemming komt vóór de tools/call. Kijk daarna naar de twee poisoning-scenario's: dezelfde server, alleen met een andere description.
Samengevat: een MCP-server geeft het model nieuwe handen. Hij geeft ook een vreemde tekst toegang tot je context: elke description en elk resultaat dat de server teruggeeft, leest het model. Voeg alleen servers toe die je vertrouwt.
Verdieping rollen, primitives, scopes, contextkosten, security
Host, client, server
De specificatie onderscheidt drie rollen. De host is de AI-applicatie (Claude Code). Die maakt per server een client aan met een eigen verbinding. De server is het programma dat context levert, of hij nu lokaal draait of bij een SaaS-leverancier. Een lokale stdio-server bedient meestal één client; een remote server veel.
MCP clients will use the
*/listmethods to discover available primitives. For example, a client can list the available tools (tools/list), provide them to a model, and execute the ones that the model calls (tools/call).
Drie primitives van de server
| Primitive | Wie gebruikt het | In Claude Code |
|---|---|---|
| Tools | het model (model-controlled) | mcp__<server>__<tool>, net als Read of Bash |
| Resources | jij, via @ | @github:issue://123 in je prompt; wordt als bijlage meegestuurd |
| Prompts | jij, als commando | /mcp__github__pr_review 456 (in het menu als /github:pr_review) |
Scopes: waar de config staat
| Scope | Laadt in | Gedeeld? | Opgeslagen in |
|---|---|---|---|
| local (standaard) | dit project | nee | ~/.claude.json, onder het projectpad |
| project | dit project | ja, via git | .mcp.json in de projectroot |
| user | al je projecten | nee | ~/.claude.json |
Bij dezelfde naam wint local van project en project van user. De hele entry van de winnaar telt: velden worden niet samengevoegd. Servers uit .mcp.json vragen in een interactieve sessie eerst om goedkeuring, want een gekloonde repo mag niet zomaar processen op je machine starten. Let op: in claude -p en in de Agent SDK kan die prompt niet verschijnen, en dan laden ze zonder te vragen.
Contextkosten: tool search
Een server met veertig tools zou met volledige schema's duizenden tokens per request kosten. Daarom staat tool search standaard aan: bij de start laden alleen de toolnamen en de server-instructies, en het volledige schema pas als het model de tool nodig heeft. /context all laat zien wat elke geladen MCP-tool kost.
Voor serverbouwers betekent dit: zet de woorden waarop gezocht wordt vooraan in je description en server-instructies, net als bij een skill-description (C1). Descriptions worden afgekapt: 4.096 tekens voor server-instructies en tools die direct laden, 16.384 voor tools die via tool search laden.
MCP en de andere primitieven
MCP levert de verbinding, maar niet de kennis. Een veelvoorkomende combinatie: een Postgres-server geeft het model query-tools, en een skill beschrijft jullie schema en querypatronen. Voor beleid zet je er een hook op: een PreToolUse-matcher mcp__postgres__.* die alles behalve SELECT blokkeert. Let op de .*: mcp__postgres zonder suffix is een exacte naam en matcht geen enkele tool.
Security: een server is code én tekst
Een MCP-server brengt twee soorten risico mee:
- Code: een lokale stdio-server is een proces met jouw rechten. Een kwaadaardige server kan alles wat jij kunt, zonder dat het model er iets mee te maken heeft.
- Tekst: descriptions, server-instructies en tool-resultaten komen in de context van het model. Daar kan een instructie in verstopt zitten (tool poisoning, een vorm van prompt injection). Een server kan zijn toollijst ook later wijzigen en
list_changedsturen. Een server die vorige maand onschuldig was, hoeft dat nu niet meer te zijn.
For trust & safety and security, clients MUST consider tool annotations to be untrusted unless they come from trusted servers.
Verdedigingen die niet afhangen van het oordeel van het model:
- Bronkeuze: schrijf je eigen servers of gebruik servers van partijen die je vertrouwt. Anthropic toetst connectors in zijn directory aan listing-criteria, maar doet geen security-audit van MCP-servers.
- Permissies: geen allow-regels voor tools die data wegschrijven of versturen; deny-regels op gevoelige bestanden (
Read(./.env)). - Hooks: een
PreToolUse-hook opmcp__.*die argumenten scant op secrets of onverwachte velden (C2). - Organisatie: met managed MCP-configuratie bepaalt een beheerder welke servers mogen draaien (D4). Een review van
.mcp.jsonlaat niet alles zien: servers uit andere scopes, connectors en plugins staan daar niet in.
Onder de motorkap transports, berichten, naamgeving, limieten
Transports en claude mcp add
Servers toevoegen
# Remote HTTP-server (aanbevolen voor cloudservices)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# Lokale stdio-server: alles na -- is het commando van de server
claude mcp add --transport stdio --env API_KEY=… airtable -- npx -y airtable-mcp-server
# Gedeeld met je team: komt in .mcp.json
claude mcp add --scope project --transport stdio weer -- python3 weer_server.py
claude mcp list # overzicht
/mcp # in een sessie: status, tools, inloggen (OAuth)
Bij een stdio-server scheidt -- de opties van Claude Code van het commando van de server. Zonder -- denkt Claude Code dat --port van de server een eigen optie is. Bij stdio zijn stdout en stdin het protocolkanaal: een server die "server gestart" naar stdout print, maakt het protocol kapot. Logging hoort op stderr.
De berichten
Alles is JSON-RPC 2.0: requests met id, responses met result of error, en notificaties zonder id. Op protocolrevisie 2025-06-18 begint een verbinding met een initialize-handshake (versie en capabilities onderhandelen, daarna notifications/initialized). Revisie 2026-07-28 is stateless: elke request draagt versie en capabilities in _meta, met een optionele server/discover. Claude Code spreekt beide en kiest per server. Daarna:
tools/call en twee soorten fouten
→ { "jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": { "name": "get_weather", "arguments": { "location": "New York" } } }
← { "jsonrpc": "2.0", "id": 3, // uitvoeringsfout: het model ziet hem
"result": { "content": [ { "type": "text", "text": "API rate limit exceeded" } ],
"isError": true } }
← { "jsonrpc": "2.0", "id": 3, // protocolfout: onbekende tool, foute argumenten
"error": { "code": -32602, "message": "Unknown tool: invalid_tool_name" } }
Het onderscheid is belangrijk: een API die faalt, is een resultaat met isError: true. Het model kan daarop reageren (opnieuw proberen, iets anders doen). Een protocolfout betekent dat client of server iets verkeerd deed.
Namen
- MCP-tools heten in Claude Code
mcp__<server>__<tool>. Die naam gebruik je in permissieregels, hook-matchers, hettools-veld van een subagent enallowed-toolsvan een skill. - Een server uit een plugin heet
mcp__plugin_<plugin>_<server>__<tool>. Een matcher op de kale servernaam vuurt daarvoor nooit (C5). - Langer dan 128 tekens? Dan laat Claude Code de tool weg, omdat de API zo'n request zou weigeren.
Limieten en gedrag
- Output: waarschuwing boven 10.000 tokens, standaardmaximum 25.000 (
MAX_MCP_OUTPUT_TOKENS). Een groter resultaat schrijft Claude Code naar een bestand; het model krijgt het pad en leest het als dat nodig is. - Dynamische tools: bij
list_changedhaalt Claude Code de nieuwe lijst op, zonder dat je opnieuw hoeft te verbinden. - Verplichte goedkeuring: een serverbouwer kan met
_meta["anthropic/requiresUserInteraction"]: trueafdwingen dat een tool altijd om toestemming vraagt, ook inbypassPermissions. Allow-regels slaan die prompt niet over. - Omgevingsvariabelen in
.mcp.json:${VAR}en${VAR:-standaard}, zodat secrets niet in git hoeven.
We encourage either writing your own MCP servers or using MCP servers from providers that you trust.
Uitgewerkt voorbeeld: een databaseserver voor je team, met vangrails
Het team wil dat Claude de testdatabase kan bevragen. In drie bestanden: de serverconfig (gedeeld via git), een hook die alleen lezen toestaat, en een skill met het schema.
.mcp.json
{
"mcpServers": {
"db": {
"command": "npx",
"args": ["-y", "@bytebase/dbhub", "--dsn", "${TEST_DB_DSN}"]
}
}
}
- Servernaam: de tools heten daardoor
mcp__db__…. Kies een korte, stabiele naam, want hij komt terug in regels en matchers. - Omgevingsvariabele: de connectiestring staat niet in git. Iedereen zet
TEST_DB_DSNin zijn eigen shell. Is hij niet gezet, dan meldt/mcpdat bij de server. De docs raden een read-only databasegebruiker aan: dat is je eerste en sterkste vangrail.
.claude/settings.json
{
"hooks": {
"PreToolUse": [
{ "matcher": "mcp__db__.*",
"hooks": [ { "type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alleen-select.sh" } ] }
]
},
"permissions": {
"deny": [ "Read(./.env)" ]
}
}
- Matcher met
.*: elke tool van deze server, ook tools die er later bijkomen. Het script controleert de SQL intool_inputen weigert alles behalveSELECTmet exit 2 (zie de database-validator in C2). - Deny-regel: een vergiftigde description of een injectie via queryresultaten kan het model niet laten lezen wat het niet mag lezen.
.claude/skills/testdb/SKILL.md
---
description: Schema en querypatronen van de testdatabase. Gebruik bij vragen over klanten, orders of facturen in de data.
---
Tabellen: customers(id, email, created_at), orders(id, customer_id, total_cents, status) …
- Bedragen staan in centen. Status is 'open' | 'paid' | 'refunded'.
- Beperk elke query tot LIMIT 100.
- Skill + MCP: de server geeft het model handen, de skill geeft het kennis. Zonder skill gokt het model naar kolomnamen en heeft het meer tool calls nodig.
- Een instructie, geen garantie. Moet
LIMITecht altijd? Laat de hook dat dan ook controleren.
Koppel een eigen MCP-server, vergiftig hem en vang het af
Starter: oefenrepo/c3-mcp/. Een MCP-server van ±100 regels Python zonder dependencies (weer_server.py), en een .env met nep-secrets. De server logt elke aanroep met argumenten naar weer_server.log.
Opdracht
- Kopieer de map naar een eigen plek en
git init. Test de server eerst los met hetprintf-commando uit de README: je ziet drie JSON-antwoorden. - Voeg hem toe:
claude mcp add --scope project weer -- python3 weer_server.py. Bekijk.mcp.json. Startclaude, keur de projectserver goed en controleer met/mcpdatweerverbonden is en één tool heeft. - Vraag: "Wat voor weer is het in Utrecht?" Bekijk de permissieprompt (welke naam, welke input?) en daarna
weer_server.log. - Vergiftig. Zet in
.mcp.json"--vergiftigd"achterweer_server.pyinargsen start Claude opnieuw. Stel dezelfde vraag. Kijk heel precies naar elke prompt voordat je iets goedkeurt. - Vang het af zonder het model. Voeg
"permissions": { "deny": ["Read(./.env)"] }toe aan.claude/settings.jsonen schrijf eenPreToolUse-hook opmcp__weer__.*die exit 2 geeft als de inputPASSWORDofKEY=bevat. Herhaal de vraag.
Verwacht resultaat
Stap 2: .mcp.json bevat "weer": { "command": "python3", "args": ["weer_server.py"] } (eventueel met "type": "stdio"). /mcp toont weer als verbonden, met tool lookup_weather.
Stap 3: een prompt voor weer - lookup_weather met city: "Utrecht". Na goedkeuring antwoordt Claude "14 °C, bewolkt". In het log staan initialize, tools/list en tools/call lookup_weather argumenten={"city": "Utrecht"}.
Stap 4: twee uitkomsten zijn mogelijk, en beide zijn leerzaam. (a) Het model volgt de instructie: het leest .env (geen prompt, want het is een leesactie in je project) en roept daarna de tool aan met de secrets in notes. De permissieprompt toont dat: weigeren! (b) Het model herkent de instructie als verdacht en negeert of meldt hem. Dan heb je geluk gehad, maar dit is modelgedrag, geen garantie. Bij een subtielere formulering kan het anders uitpakken.
Stap 5: de Read op .env wordt geweigerd door de deny-regel. Komen er toch secrets in de input (bijvoorbeeld als het model ze al eerder had gelezen), dan blokkeert de hook de call. In weer_server.log verschijnt geen tools/call met notes.
Als het niet werkt, kijk naar …
- Server niet verbonden. Klopt de werkmap? Een relatief pad in
argswerkt alleen als Claude in de projectroot start. Robuuster:"args": ["${CLAUDE_PROJECT_DIR:-.}/weer_server.py"]. Draaiclaude --debugvoor de foutmelding van de server. - Server staat op "Pending approval". Projectservers vragen eerst om goedkeuring. Start een interactieve sessie en accepteer, of reset je keuzes met
claude mcp reset-project-choices. - Protocolfouten. Print je zelf iets naar stdout in de server? Dat breekt JSON-RPC. Debug-uitvoer hoort op stderr.
- Hook vuurt niet. De matcher moet
mcp__weer__.*zijn (met.*), hoofdlettergevoelig.mcp__weerzonder suffix is een exacte naam en matcht niets. - Vergiftiging lijkt niets te doen. Herstart Claude na het wijzigen van
.mcp.json, en controleer in het log dat ertools/list (vergiftigde description)staat.