MCP server authenticatie implementatiegids: volgens de nieuwste specificatie

Enkele dagen geleden (18 juni 2025) bracht het MCP (Model Context Protocol) team de nieuwste versie uit van de MCP Spec (2025-06-18). Deze update bevat een belangrijke wijziging in de authenticatiespecificatie. MCP Servers geven niet langer access tokens uit als een Authorization Server. In plaats daarvan zullen ze access tokens consumeren en resources aanbieden als een Resource Server.

Als een van de maintainers van MCP Auth (een plug-and-play MCP Server authenticatiebibliotheek), heb ik ondersteuning voor de nieuwste MCP authenticatiespecificatie aan dit project toegevoegd. Op basis van mijn praktische ervaring laat ik je zien hoe je authenticatie kunt implementeren in je eigen MCP Server, geheel in lijn met de nieuwste specificatie.

Dit artikel helpt je:

• Begrijpen hoe MCP authenticatie werkt onder de nieuwe authenticatiespecificatie
• Helder krijgen wat MCP Servers als Resource Server moeten implementeren volgens de vereisten in de MCP authenticatiespecificatie
• Leidraad geven voor het implementeren van auth support die voldoet aan de nieuwste MCP authenticatiespecificatie voor jouw MCP Server
• Aandachtspunten en beveiligingskwesties signaleren die vaak over het hoofd worden gezien bij implementatie van de MCP authenticatiespecificatie

Let op dat dit artikel:

• Ervan uitgaat dat de lezer basiskennis van JWT (JSON Web Token) heeft. De structuur van JWT, verificatie van ondertekening, en andere basisconcepten worden niet diepgaand besproken. Raadpleeg voor details Auth Wiki - JWT
• Geen uitgebreide uitleg geeft over de verschillende RFC's waarop de MCP authenticatiespecificatie steunt. Het biedt alleen implementaties die aan deze RFC eisen voldoen
• Niet ingaat op de implementatie en interactie tussen MCP Client en Authorization. Dit wordt gewoonlijk geïmplementeerd door LLM clients en providers van authorization servers die MCP ondersteunen op basis van specificaties. MCP Server ontwikkelaars hoeven en mogen hier niet op ingrijpen. Zie voor details OAuth Client en Authorization Server
• Alle access tokens in dit artikel worden verondersteld JWT's te zijn, het meest gebruikte formaat. Andere vormen van tokens moeten volgens de documentatie van de betreffende authorization server provider worden toegepast.

Hoe werkt MCP authenticatie?#

Volgens de nieuwste MCP authenticatiespecificatie wordt de MCP auth flow als volgt weergegeven:

1. De MCP Client vraagt resources op van de MCP Server bij https://github-tools.com. Omdat de gebruiker nog niet is ingelogd, bevat de HTTP-authorization header van dit verzoek geen access token.

2. De MCP Server ziet dat het authorisatie header van het MCP Client verzoek geen access token bevat. Hij retourneert een HTTP 401 fout aan de MCP Client. Dit foutbericht bevat een WWW-Authenticate header met daarin de URL naar de resource metadata van de MCP Server (de waarde van het resource_metadata veld).

3. De MCP Client haalt de waarde van resource_metadata uit de teruggegeven WWW-Authenticate header (bv. https://github-tools.com/.well-known/oauth-protected-resource) en vraagt de resource metadata op die de MCP Server als Resource Server aanbiedt. Deze metadata bevat zaken als authorization_servers en scopes_supported, en geeft de MCP Client inzicht in hoe en van welke authorization server een token met bepaalde rechten gehaald kan worden.

4-8. De MCP Client vraagt volgens de metadata van de authorization server de server metadata op, waarna een OAuth 2.1 autorisatieflow plaatsvindt met de authorization server en de client uiteindelijk een access token ontvangt.

9. De MCP Client stuurt het verkregen access token mee met een nieuw resourceverzoek aan de MCP Server.

10. De MCP Server retourneert na controle van het token de gevraagde resource. Vanaf dan verloopt alle communicatie tussen MCP Client en MCP Server met een geldig token.

Hierna leggen we stap voor stap uit hoe je het authenticatiemechanisme van je MCP Server volgens de workflow implementeert.

Ongeautoriseerde verzoeken afhandelen: 401 fout en WWW-Authenticate header retourneren#

Zoals in het bovenstaande proces, als de MCP Client een verzoek zonder access token naar de MCP Server stuurt, retourneert de MCP Server een HTTP 401 Unauthorized fout met een WWW-Authenticate header die de URL van de MCP Server resource metadata bevat.

Volgens de foutafhandeling in de MCP authenticatiespecificatie, moet de MCP Server niet alleen een 401 fout retourneren bij verzoeken zonder access token, maar ook als het access token ongeldig is, samen met een WWW-Authenticate header.

Nu we weten wanneer we een 401 fout moeten retourneren, hoe bouwen we dan de juiste WWW-Authenticate header?

Volgens RFC9728 Sectie 5.1, moet de WWW-Authenticate header een resource_metadata parameter bevatten die verwijst naar de URL van de beschermde resource metadata.

Het basisformaat is:

Hier geeft Bearer het type authentication scheme aan, namelijk dat voor toegang tot OAuth 2.0-gereserveerde resources een bearer token vereist is (zie: MDN documentatie). De waarde van de resource_metadata parameter is de volledige URL van het metadata-endpoint dat je MCP Server levert.

De daadwerkelijke implementatie kan er zo uitzien:

Wanneer de MCP Client zo’n 401 fout ontvangt, zal hij via de resource_metadata uit de WWW-Authenticate header de resource metadata van de MCP Server benaderen. Daarna initieert hij, op basis van deze informatie, een autorisatieverzoek aan de opgegeven authorization server voor een geldig access token.

We weten nu wanneer we een 401 fout en een resource_metadata URL moeten teruggeven. Maar hoe maak je zo’n resource metadata URL en wat hoort er in die metadata te staan? Dat volgt hierna.

Mechanisme voor resource metadata discovery implementeren#

Volgens de MCP authenticatieworkflow vraagt de MCP Client na ontvangst van een 401 fout direct de resource metadata bij de MCP Server op. De MCP Server dient als Resource Server een resource metadata discoverymechanisme te bieden.

URL-pad van het metadata-endpoint bepalen#

In het OAuth-systeem worden URLs gebruikt om resources aan te duiden. Deze adressering heet een "resource indicator". Volgens RFC9728 moet resource metadata onder het specifieke pad /.well-known worden geplaatst.

Als je MCP Server (zoals https://github-tools.com) maar één dienst biedt, moet het metadata-endpoint zijn:

Als je meerdere verschillende MCP services op één host hebt, krijgt elke service een eigen metadata-endpoint. Bijvoorbeeld bij het platform https://api.acme-corp.com:

• https://api.acme-corp.com/github - GitHub integratiedienst
• https://api.acme-corp.com/slack - Slack integratiedienst
• https://api.acme-corp.com/database - Database querydienst

Worden de metadata-endpoints:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Het voordeel is dat elke service eigen permissies en authorization server instellingen kan hebben, bijvoorbeeld:

• GitHub dienst gebruikt de GitHub OAuth server en vereist github:read, github:write
• Slack via Slack OAuth server met slack:channels:read, slack:messages:write
• Database via interne authorisatieserver met db:query

Samengevat volgen de endpoints dit patroon:

Zo kun je bijvoorbeeld uit een resource indicator het metadata endpoint bepalen:

Resource metadata response samenstellen#

Na het bepalen van het endpoint, moet deze een JSON responstype retourneren volgens RFC9728.

In de praktijk concentreren we ons voornamelijk op vier kernvelden.

Het eerste is het resource veld, dit is de resource identifier en moet overeenkomen met het resource-adres dat de MCP Client wil benaderen.

Dan het authorization_servers veld, een array die specificeert bij welke authorization server(s) een access token gevraagd moet worden. Volgens RFC 9728 is dit veld optioneel, maar volgens MCP authenticatiespecificatie verplicht, zodat de MCP Client altijd weet bij welke server een token aangevraagd moet worden. Zonder deze info kan de MCP Client niet verder in de OAuth flow.

Vervolgens het scopes_supported veld, waarin alle door deze Resource Server ondersteunde permissies bekend worden gemaakt.

Tot slot het bearer_methods_supported veld, waarmee je MCP Client weet op welke manier een access token aangeboden moet worden. In actuele praktijk zetten we dit op ["header"], zodat een access token via de HTTP Authorization header wordt gestuurd na autorisatie.

Een concreet voorbeeld voor de resource metadata voor https://github-tools.com:

Hiermee geef je de MCP Client enkele belangrijke aanwijzingen: hij wil de resource https://github-tools.com benaderen, heeft een token van https://auth.github-tools.com nodig met eventueel rechten als github:read, github:write of repo:admin, en moet het token via de HTTP Authorization header versturen.

Voor de meeste situaties voldoen deze vier velden. In bijzondere gevallen kun je alle velden uit RFC9728 raadplegen.

Access tokens valideren#

Nadat de MCP Client een access token van de authorization server heeft ontvangen, stuurt de Client dit token mee voor toegang tot de MCP Server.

Let als volgt op bij het valideren van access tokens in de MCP Server:

1. Voer basis tokenvalidatie altijd uit aan de hand van de configuratie van de MCP Server, niet automatisch op info uit het token zelf.
2. Controleer of de audience van het token overeenkomt met de eigen server, zodat het token specifiek voor deze resource bedoeld is.
3. Controleer permissies (scopes) correct.

Gebruik configuratie van MCP Server voor access token validatie#

Als een access token wordt ontvangen, zal het token altijd de authorization server info (issuer) bevatten. Sommige ontwikkelaars halen direct op basis van de issuer uit het token informatie om het token te valideren. Zeker als er meerdere authorization servers zijn geconfigureerd, zoals in:

In dat geval nemen sommige developers gewoon de issuer uit een (onbevestigd) token en gebruiken dit voor de validatie. Maar een aanvaller kan een eigen valse authorization server en fake access token opzetten. Als je alleen op de issuer uit het token afgaat, kan de aanvaller via zijn eigen server tokens goedkeuren!

De juiste werkwijze is:

• Bij één authorization server: valideer altijd op de in de backend geconfigureerde authorization server
• Bij meerdere authorization servers: haal de (onbevestigde) issuer uit het token, maar check of deze in je eigen lijst van toegestane authorization servers staat. Is dit niet zo? Token weigeren!

Zorg bij validatie altijd voor strikte controle op issuer.

Met de jose JWT-bibliotheek ziet dat er zo uit:

Audience van token controleren#

De sectie Token Audience Binding and Validation schrijft voor dat de client bij het aanvragen van een access token bij de authorization server het doelresource (de audience) moet opgeven waarvoor het token zal worden gebruikt. De MCP Server moet vervolgens controleren of de audience in het token overeenkomt met de eigen resource identifier.

Dit mechanisme steunt op Resource Indicators for OAuth 2.0 (RFC 8707):

1. Client vraagt access token met resource parameter (bijv. https://github-tools.com)
2. Authorization server bindt deze resource aan het access token, bij JWT’s als het audience (aud) attribuut
3. MCP Server moet bij validatie controleren of het audience veld uit het token exact overeenkomt met de eigen resource

Voorbeeld voor https://github-tools.com:

Deze audience validatie is essentieel om tokenmisbruik te voorkomen. Zonder deze controle kunnen tokens die voor andere services zijn uitgegeven mogelijk worden gebruikt op jouw MCP Server.

Scope validatie#

Sommige MCP Servers beheren intern verschillende resources met verschillende permissies per gebruiker.

Zodra het access token geldig is, moet je controleren of het token de juiste scopes (rechten) bevat. Dit doe je door na te gaan of het scope veld het vereiste recht omvat:

Volgens de MCP authenticatiespecificatie moet je bij onvoldoende scope een 403 Forbidden fout retourneren.

Conclusie#

Na het lezen van dit artikel kun je authenticatie in je eigen MCP Server volgens de nieuwste specificaties implementeren. Let daarbij herhaaldelijk op: valideer tokens strikt, configureer je metadata correct en check altijd de audience.

Ben je bezig met een MCP Server, probeer dan de MCP Auth bibliotheek. Die implementeert alle besproken functionaliteit zodat je snel kunt integreren.

Vragen? Bespreek ze gerust op GitHub. Laten we samen het MCP ecosystem verder verbeteren.