MCP-authenticatie: API-key of OAuth

MCP-authenticatie werkt in mcp-core met één token per connectie. Elk verzoek naar /mcp of /sse moet het token van een connectie op je licentie meesturen; de server zoekt het op en past de tools en modi van die connectie toe. De variabele AUTH_STRATEGY bepaalt hoe een client bewijst wie hij is: met een API-key (de standaard) of via OAuth.

Hoe werkt MCP-authenticatie in mcp-core?

Elk verzoek doorloopt één authenticatiestap voordat het een tool bereikt. mcp-core leest het token, vergelijkt het met de connecties uit de laatste licentiecheck en koppelt de bijbehorende connectie aan het verzoek. Die connectie bepaalt welke tools geregistreerd worden en in welke modus. Tokens worden in constante tijd vergeleken.

Er bestaat geen licentiebrede reservesleutel. Een licentie zonder connecties laat niemand binnen: elk verzoek krijgt 401 Unauthorized. Als je je bundel downloadt (zie MCP Core installeren), wordt er automatisch een eerste connectie “Default install” aangemaakt, zodat een verse installatie direct werkt.

Een geweigerd verzoek geeft dit antwoord, met een header WWW-Authenticate: Bearer realm="MCP Core":

HTTP/1.1 401 Unauthorized
{"error":"Unauthorized"}

Waar zet de client het token?

Voor MCP-authenticatie is de standaardplek de header Authorization met het schema Bearer:

Authorization: Bearer YOUR_CONNECTION_TOKEN

Sommige connectorschermen bieden alleen een vaste lijst headernamen. Daarvoor accepteert mcp-core het kale token (zonder Bearer-prefix) ook in X-Api-Key, Api-Key, ApiKey, Api-Token, X-Auth-Token of X-Access-Token. Welke header je gebruikt, maakt niet uit voor wat de connectie mag.

Wat doet de API-key-strategie?

API-key is de standaard voor MCP-authenticatie en de waarde waarmee je bundel geleverd wordt:

AUTH_STRATEGY=apikey

Het token van elke connectie is de API-key ervan. Je kopieert het via Mijn account → Licenties, op het tabblad Connecties van je licentie. Dit past bij de standaardopzet: één zelf gehoste installatie per klant, achter je eigen firewall of reverse proxy.

Sommige clients, waaronder de custom connector van Claude Desktop, eisen tijdens de setup een OAuth-achtige handshake, ook als een statisch token volstaat. mcp-core beantwoordt die handshake op /oauth/authorize en /oauth/token zonder echte login:

• De link onder AI koppelen (/mcp/<token>) bevat het token in het adres. De meeste clients hebben dan helemaal geen handshake nodig; begint er toch een, dan geeft hij dat adres mee en rondt mcp-core de handshake af voor die connectie.
• Stuurt de client je connectietoken mee als Client ID, dan rondt mcp-core de handshake direct af voor die connectie.
• De code die mcp-core uitgeeft is eenmalig, verloopt na 10 minuten en hoort bij de PKCE-challenge van de client, die verplicht is. Het token wordt pas overgedragen in de laatste /oauth/token-uitwisseling.

Een verzoek zonder connectietoken krijgt een pagina “Seat link required” en geen code. Versies vóór 2.3.1 toonden daar een verbindingskiezer, zonder wachtwoord; werk bij met ./mcp-update.sh als je die nog draait. Zie je zelf gehoste MCP-server beveiligen.

Wanneer gebruik je de OAuth-strategie?

De OAuth-strategie voegt een echte loginpagina toe, met gebruikersnaam en wachtwoord:

AUTH_STRATEGY=oauth

Die is bedoeld voor een server die meerdere mensen op afstand gebruiken, elk met een eigen login. De gebruikersaccounts zijn een lokale lijst op die installatie, ingesteld in OAUTH_USERS; het zijn niet je WordPress- of AddoCore-accounts. Een login werkt alleen als de gebruikersnaam gekoppeld is aan een connectie op de licentie. Houd voor een standaard zelf gehoste installatie apikey aan.

Een login stuurt zijn code alleen naar de eigen callback van Claude of een lokaal adres, tenzij je andere adressen opgeeft in OAUTH_REDIRECT_URIS. PKCE is verplicht, en na 10 verkeerde wachtwoorden vanaf één adres of voor één gebruikersnaam wacht de login 15 minuten.

Welke endpoints slaan MCP-authenticatie over?

Een paar routes zijn zonder token bereikbaar, omdat clients ze nodig hebben voordat ze kunnen authenticeren:

• /health: status en licentiestatus. Welke tools actief zijn, ziet alleen een connectie, via mcp_status.
• /.well-known/oauth-authorization-server en /.well-known/oauth-protected-resource: discovery-metadata die sommige clients als eerste lezen. De adressen daarin komen uit SERVER_URL.
• /oauth/authorize en /oauth/token: de handshake hierboven.

Al het andere, inclusief /mcp, /sse en /message, vereist een geldig token. Het meegeleverde compose-bestand bindt poort 3200 aan 127.0.0.1, dus standaard is geen van deze routes van buiten de host bereikbaar.

Hoe vernieuw of trek je een token in?

Gebruik de kolom Acties op het tabblad Connecties. Regenerate token maakt een nieuw token voor die connectie; Revoke verwijdert de connectie. Andere connecties blijven werken. De draaiende server ziet de wijziging bij de volgende licentiecheck; pas hem daarom direct toe met:

docker exec mcp-core npm run refresh-license

Werk na het vernieuwen het token bij overal waar die connectie gebruikt wordt. Voor “Default install” geldt dat ook voor BEARER_TOKEN in .env en claude-plugin/.mcp.json.

Hoe houd je MCP-authenticatie veilig op een netwerk?

Houd de standaardbinding op 127.0.0.1 aan, tenzij je toegang op afstand nodig hebt. Heb je dat wel, zet dan een reverse proxy met HTTPS voor de container, zodat tokens nooit onversleuteld over het netwerk gaan, en stel SERVER_URL in op het publieke adres. De server staat cross-origin-verzoeken vanaf elke origin toe, dus het token is het enige wat tussen een aanroeper en je tools staat. Behandel het als een wachtwoord: één per persoon of apparaat, nooit gedeeld in een chat of gecommit in git.

Alles wat je moet nalopen staat in je zelf gehoste MCP-server beveiligen.

Welke fouten bij MCP-authenticatie komen vaak voor?

• Een token van een andere licentie gebruiken, of een token dat vernieuwd is. De log toont Token rejected.
• Bearer voor het token zetten in een X-Api-Key-header. Alleen Authorization gebruikt die prefix.
• Verwachten dat een intrekking werkt vóór de volgende check. Draai het refresh-commando.

Met MCP-authenticatie per connectie krijgt iedereen een eigen token dat je kunt intrekken. Ga verder met MCP-connecties om ze aan te maken, of koppel Claude aan de server. Hoe een token aan tools gekoppeld wordt, lees je bij entitlements vs. toolmodi.