Gids

Een MCP-server bouwen met OAuth 2.1

Wij draaien twee MCP-servers op afstand in productie. Met de ene bedient Claude ons sales-CRM, met de andere geven online verkopers hun Salestreak-werkruimte in handen van een AI-agent. Beide hebben een eigen OAuth 2.1-autorisatieserver, gebouwd in Rails. In deze gids lees je wat we bouwden, waarom we het zo deden en wat we iedereen zouden meegeven die er zelf een bouwt.

Martin Balk Oprichter van Balk.dev Bijgewerkt op 9 min leestijd
Op deze pagina
  1. Wat een MCP-server eigenlijk is
  2. Zo werkt autorisatie in MCP
  3. De twee discovery-documenten
  4. Dynamische registratie en PKCE
  5. Tokens: audience, levensduur en opslag
  6. Het toestemmingsscherm bepaalt wie mag koppelen
  7. Ontwerp tools rond taken, niet rond endpoints
  8. Vangrails horen op de server
  9. Vaste instructies en testen met Claude

Wat een MCP-server eigenlijk is

Het Model Context Protocol (MCP) is een open standaard waarmee AI-assistenten zoals Claude en ChatGPT tools in andere software aanroepen. Een MCP-server beschrijft zijn tools (een naam, een omschrijving en een JSON Schema voor de input), de assistent bepaalt wanneer hij ze aanroept, en de server voert elke aanroep uit binnen de regels die jij eromheen zet. Het hele protocol staat in de specificatie.

Een lokale MCP-server draait op de computer van de gebruiker en praat via stdio. Een server op afstand is een webendpoint waar veel mensen op koppelen, en daar komt autorisatie om de hoek kijken. Onze twee servers draaien allebei op afstand: een voor ons eigen sales-CRM en POST /mcp/shop voor Salestreak-werkruimtes.

Onder de motorkap is het JSON-RPC 2.0. In protocolversie 2025-06-18 begint een sessie met initialize, haalt de client de tools op met tools/list en roept hij ze aan met tools/call. Onze servers antwoorden met gewone JSON in plaats van een SSE-stream, wat het streamable HTTP-transport toestaat. Een tool-aanroep is dus één POST en één antwoord:

POST /mcp/shop HTTP/1.1
Host: app.example.com
Authorization: Bearer <access token>
Content-Type: application/json

{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
 "params": {"name": "adjust_stock",
            "arguments": {"variant_id": "MUG-0141", "delta": 12, "reason": "received"}}}
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [{ "type": "text", "text": "{\"sku\": \"MUG-0141\", \"on_hand\": 53, \"previous\": 41}" }],
    "isError": false
  }
}

Zo werkt autorisatie in MCP

MCP verzint geen eigen authenticatie. De autorisatiespecificatie bouwt op OAuth 2.1 en een handvol RFC's, en de hele flow is te ontdekken: de gebruiker plakt één URL in zijn assistent en de client zoekt de rest zelf uit.

  1. 1

    De client roept de server aan zonder token

    De server antwoordt met 401 Unauthorized en een WWW-Authenticate-header die naar zijn protected resource metadata wijst (RFC 9728).

  2. 2

    De client leest de protected resource metadata

    Dat document noemt de resource en de autorisatieserver die er tokens voor uitgeeft.

  3. 3

    De client leest de metadata van de autorisatieserver

    Via /.well-known/oauth-authorization-server (RFC 8414) leert hij de endpoints voor autoriseren, tokens en registratie, en dat PKCE met S256 verplicht is.

  4. 4

    De client registreert zichzelf

    Met dynamische clientregistratie (RFC 7591) krijgt hij een client_id zonder dat iemand een formulier invult.

  5. 5

    De gebruiker keurt goed op een toestemmingsscherm

    De client opent de autorisatie-URL met een PKCE-challenge en een resource-parameter die de MCP-server noemt (RFC 8707). De gebruiker logt in en geeft toestemming.

  6. 6

    De client ruilt de code in voor tokens

    Hij stuurt de code en de PKCE-verifier naar het token-endpoint en krijgt een access token en een refresh token terug. Het access token gaat als bearer-header mee met elk MCP-verzoek.

# Every unauthenticated request gets a pointer to the discovery document (RFC 9728).
def unauthorized_with_discovery_hint
  response.set_header(
    "WWW-Authenticate",
    %(Bearer resource_metadata="#{request.base_url}/.well-known/oauth-protected-resource/mcp/#{audience}")
  )
  head :unauthorized
end

De twee discovery-documenten

Beide documenten zijn kleine JSON-antwoorden. Wij bouwen ze per verzoek op basis van de host, zodat staging en productie nooit naar elkaar verwijzen.

# GET /.well-known/oauth-authorization-server  (RFC 8414)
def authorization_server_metadata
  render json: {
    issuer: request.base_url,
    authorization_endpoint: "#{request.base_url}/oauth/authorize",
    token_endpoint: "#{request.base_url}/oauth/token",
    registration_endpoint: "#{request.base_url}/oauth/register",
    response_types_supported: ["code"],
    grant_types_supported: %w[authorization_code refresh_token],
    code_challenge_methods_supported: ["S256"],
    token_endpoint_auth_methods_supported: ["none"]
  }
end

# GET /.well-known/oauth-protected-resource/mcp/shop  (RFC 9728)
def protected_resource_metadata
  render json: {
    resource: "#{request.base_url}/mcp/shop",
    authorization_servers: [request.base_url],
    bearer_methods_supported: ["header"]
  }
end

De waarde none voor token_endpoint_auth_methods_supported betekent publieke clients: er is geen client secret, dus PKCE doet het werk dat een secret anders zou doen. Dat is de juiste opzet als elke assistent zichzelf registreert. Een client_id geeft op zichzelf geen enkel recht, want elke autorisatie gaat nog altijd langs jouw toestemmingsscherm.

Draai je meer dan één connector op dezelfde autorisatieserver, geef dan elke connector een eigen protected resource-document. Salestreak serveert er één per connector, zodat een client die naar het shop-endpoint vraagt te horen krijgt dat hij een shop-token nodig heeft en geen sales-token.

Dynamische registratie en PKCE

Met dynamische registratie kan elke client die de standaard volgt zichzelf registreren. Wij accepteren dat met twee controles: redirect-URI's moeten absolute https-URL's zijn (of http://localhost tijdens het ontwikkelen), en later accepteren we alleen exact geregistreerde URI's. Een geregistreerde client heeft zelf geen rechten. Hij kan alleen een autorisatie starten die een mens daarna moet goedkeuren.

# Authorization codes are single use, expire after ten minutes and are
# stored only as a SHA-256 digest. Redemption checks the PKCE verifier.
def redeem!(code_verifier:, redirect_uri:)
  return false if redeemed_at.present? || expires_at.past?
  return false unless redirect_uri.to_s == self.redirect_uri
  return false unless pkce_valid?(code_verifier)

  update!(redeemed_at: Time.current)
  true
end

def pkce_valid?(verifier)
  return false if verifier.blank?

  expected = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
  ActiveSupport::SecurityUtils.secure_compare(expected, code_challenge)
end

We accepteren alleen S256 als challenge-methode, en bij elke mismatch krijg je hetzelfde antwoord: invalid_grant. Een mislukte inwisseling verraadt dus niets over de reden.

Tokens: audience, levensduur en opslag

De spec is duidelijk: een MCP-server mag alleen tokens accepteren die voor hemzelf zijn uitgegeven, en mag het token van een client nooit doorgeven aan een andere API. In de praktijk komt dat neer op drie regels.

  • Eén audience per token. De resource-parameter bepaalt voor welke connector een token is. Salestreak slaat die audience op bij de grant en het token en controleert hem bij elk verzoek, zodat een shop-token nooit het sales-endpoint opent.
  • Eén werkruimte en één gebruiker. Voor de shop-connector vraagt het toestemmingsscherm welke werkruimte je wilt koppelen. Het token hoort bij die werkruimte en bij de persoon die toestemming gaf, en de agent werkt met de rol van die persoon. Verlaat diegene de werkruimte, dan verliest de agent zijn toegang mee.
  • Kort geldig, gehasht, geroteerd. Access tokens zijn 24 uur geldig en refresh tokens 90 dagen. Ruwe tokens geven we één keer terug, en we bewaren alleen SHA-256-digests. Elke refresh trekt het oude paar in en geeft een nieuw paar uit, wat de spec voor publieke clients verplicht stelt.
ACCESS_TTL  = 24.hours
REFRESH_TTL = 90.days

# Raw tokens are returned once; only SHA-256 digests are stored.
def self.authenticate(raw_access, audience:)
  return nil if raw_access.blank?

  token = find_by(access_token_digest: Digest::SHA256.hexdigest(raw_access))
  return nil if token.nil? || token.revoked_at.present? || token.expires_at.past?
  return nil if token.audience != audience # a shop token never opens the sales endpoint

  token
end

# Rotation: the old pair is revoked in the same transaction that issues the new one.
def self.refresh!(raw_refresh, client:)
  token = find_by(refresh_token_digest: Digest::SHA256.hexdigest(raw_refresh.to_s))
  return nil if token.nil? || token.oauth_client_id != client.id
  return nil if token.revoked_at.present? || token.refresh_expires_at.past?

  transaction do
    token.update!(revoked_at: Time.current)
    issue!(client: client, user: token.user, audience: token.audience, organization: token.organization)
  end
end

Het toestemmingsscherm bepaalt wie mag koppelen

Op het toestemmingsscherm leven je bedrijfsregels over toegang. Die verschillen bij ons per connector:

  • Sales-connector: alleen een ingelogde beheerder kan hem goedkeuren, omdat hij de hele salesdatabase openstelt. Iedereen anders krijgt een duidelijke weigering.
  • Shop-connector: elk lid van een werkruimte kan hem goedkeuren, maar kiest dan één van zijn eigen werkruimtes, en het token draagt zijn rol. Eigenaren en beheerders mogen schrijven; editors en kijkers alleen lezen.

Leg in gewone taal uit wat de connector straks kan, en geef mensen een manier om hem later weer in te trekken. In Salestreak staan gekoppelde agents in de instellingen van de werkruimte, waar de verkoper ze met één klik ontkoppelt.

Ontwerp tools rond taken, niet rond endpoints

Een assistent kiest tools op basis van hun naam en omschrijving. Spiegel je je REST-API één op één, dan krijgt hij tientallen low-level aanroepen en geen idee hoe die samenhangen. Wij ontwerpen tools rond het werk dat mensen echt uit handen geven: adjust_stock met een reden en een notitie, generate_description voor alle talen tegelijk, verify_email voordat er moeite in een contact gaat zitten.

  • Zeg waar de tool voor is en wanneer je hem gebruikt. Een omschrijving als ‘gebruik set voor een aantal, delta voor een wijziging’ scheelt het model giswerk.
  • Accepteer de kenmerken die mensen gebruiken. Onze shop-tools nemen een product-id of slug, een variant-id of SKU, een order-id of ordernummer.
  • Geef fouten terug waar de agent iets mee kan. Een geweigerde aanroep noemt de reden en de oplossing: welke rol nodig is, welke limiet van het abonnement bereikt is, welk veld ontbreekt.
  • Weiger werk dat al loopt. Renders en publicaties naar marktplaatsen draaien als achtergrondtaken; de tools melden hun status en zetten hetzelfde werk niet twee keer in de wachtrij.
{
  name: "adjust_stock",
  description: "Set or change the on-hand stock of a tracked variant at one location, " \
               "with a ledger entry. Use set for a count, delta for a change (+12 received, -1 damaged).",
  inputSchema: {
    type: "object",
    properties: {
      variant_id: { type: "string", description: "Variant id or SKU" },
      set:        { type: "integer", description: "New on-hand count" },
      delta:      { type: "integer", description: "Change to apply instead of set" },
      reason:     { type: "string", enum: MOVEMENT_REASONS }
    },
    required: ["variant_id"]
  }
}

def tool_adjust_stock(args)
  require_manage!("adjust stock")   # owners and admins only
  variant = find_variant(args)      # looked up inside the token's workspace
  raise ToolError, "pass set (a count) or delta (a change)" if args[:set].blank? && args[:delta].blank?
  # ... update the stock level and write a ledger entry in one transaction
end

Zo pakken we het ook aan als we AI aan een bestaand product toevoegen: begin bij het werk dat mensen doen, niet bij de API die toevallig al bestaat.

Vangrails horen op de server

Instructies in een prompt zijn een verzoek. Controles op de server zijn een garantie. We gebruiken allebei, maar alles wat ertoe doet, dwingen we af in code.

  • Baken elke query af. Elke shop-tool zoekt records op via de werkruimte van het token, dus een id uit een andere werkruimte levert simpelweg ‘niet gevonden’ op.
  • Respecteer de limieten van het abonnement. Tools controleren dezelfde rechten als de app: productlimiet, beeldtegoed, resolutie. Een geweigerde aanroep noemt de limiet en waar je kunt upgraden.
  • Zet een mens voor onomkeerbare acties. Op de sales-connector draaien de tools die mails goedkeuren en inplannen alleen als de persoon in het gesprek daar expliciet om vraagt, en de gebruiker achter het OAuth-token wordt vastgelegd als beoordelaar.
  • Weiger input die de regels breekt. De server wijst concepten af die de huisstijl of het maximum aantal follow-ups overtreden, wat de agent ook van plan was.
  • Leg alles vast. Elke goedkeuring wordt opgeslagen als event, met wie hem gaf en via welk kanaal.
# @user is the person behind the OAuth token, recorded as the reviewer.
def approve_one(draft)
  if draft.company.suppressed_for_push?
    return { draft_id: draft.id, approved: false, reason: "company is suppressed" }
  end

  draft.approve!(@user)
  OutreachEvent.record!(draft: draft, event_type: "draft_approved",
                        payload: { "reviewed_by" => @user.email, "via" => "mcp" })
  { draft_id: draft.id, approved: true }
end

Vaste instructies en testen met Claude

Het antwoord op initialize kan instructions bevatten: tekst die de client voor de hele sessie als vaste context laadt. Wij gebruiken dat voor het draaiboek: de volgorde van het werk, wat eerst gecontroleerd moet worden, de huisstijl en wat de agent nooit op eigen houtje mag doen. De shop-server van Salestreak leert de agent de route van product aanmaken tot publiceren, plus regels als: verzin nooit prijzen, voorraad of materialen.

Test daarna met de echte client. Voeg de server in Claude toe als custom connector, doorloop de toestemmingsflow op een staging-omgeving en geef hem echte taken. Kijk welke tool hij kiest, welke argumenten hij verkeerd gokt en waar hij vraagt om iets wat de server hem had kunnen vertellen. Elke verrassing wordt een betere omschrijving, een duidelijkere foutmelding of een nieuwe controle op de server.

Houd geautomatiseerde tests bij voor het saaie deel: elke tool-omschrijving heeft een handler en is als JSON te serialiseren, een token voor de ene audience wordt geweigerd op de andere, en een lid dat een werkruimte verlaat, neemt de toegang van de agent mee.

Veelgestelde vragen

Heb ik OAuth nodig voor een MCP-server?

Alleen voor servers op afstand die namens een gebruiker werken. De spec maakt autorisatie optioneel, en lokale servers die via stdio draaien, halen hun gegevens uit de omgeving. Zodra meerdere mensen via internet op een server koppelen, is OAuth de manier om te weten wie er aanroept en wat diegene mag.

Kan ik mijn bestaande loginsysteem als autorisatieserver gebruiken?

Ja. De autorisatieserver kan in je eigen app leven, zoals bij ons, of een aparte identity provider zijn, zolang die de metadata publiceert waar MCP-clients naar zoeken en PKCE ondersteunt. Het toestemmingsscherm wil je meestal zelf ontwerpen.

Waar is de resource-parameter voor?

Die vertelt de autorisatieserver voor welke MCP-server het token is (RFC 8707). Sla hem op bij het token en controleer hem bij elk verzoek, zodat een token voor de ene connector niet op een andere werkt.

Hoe lang moet een MCP-access token geldig zijn?

Kort. De spec vraagt autorisatieservers om kortlevende access tokens uit te geven en refresh tokens voor publieke clients te roteren. Wij gebruiken 24 uur voor access tokens en 90 dagen voor roterende refresh tokens, opgeslagen als hash.

Kan een AI-agent via MCP mails versturen of geld uitgeven?

Technisch wel, en precies daarom laten we hem dat niet alleen beslissen. Op onze servers draaien tools die versturen of geld kosten alleen op expliciete instructie van een mens, controleert de server de regels en leggen we vast wie wat goedkeurde. Lees hoe we MCP-servers voor klanten bouwen.

Een MCP-server voor je product?

We bouwden er twee, met OAuth, afgebakende tools en menselijke goedkeuring. Vertel wat een agent in jouw software moet kunnen, dan vertellen wij wat ervoor nodig is.

martin@balk.dev

Je hoort meestal binnen één werkdag van ons.

Handig om te noemen

  • Wat je wilt bouwen, in een paar zinnen
  • Wie het gaat gebruiken
  • Een eventuele deadline of lanceerdatum
  • Systemen en tools waar het mee moet samenwerken