MCP-auth i 2026: fire opt-in-valg avgjør om SDK-en følger standarden

En MCP-klient i TypeScript følger ikke auth-kravene i 2026-07-28-revisjonen bare ved å velge protokollversjon. SDK-ens migreringsguide peker på fire valg som må gjennomgås: send «iss» fra OAuth-tilbakekallet, bevar utstederen på lagrede legitimasjoner, lagre discovery state og bestem hvordan utilstrekkelig scope skal håndteres. Det siste valget står allerede på «reauthorize» som standard, men må passe klientens autorisasjonsflyt.

MCPs publiserte revisjon fra 28. juli 2026 krever at klienten validerer «iss» før den veksler inn en autorisasjonskode, og binder klientlegitimasjon til autorisasjonsserveren som utstedte den. Oppgraderingen berører derfor både tilbakekallet og lagringslaget. En vellykket forbindelse til en server med den nye protokollrevisjonen viser ikke alene at disse kontrollene er på plass.

Velg protokollflyt separat fra auth

En håndkonstruert klient i TypeScript SDK v2 bruker den eldre oppstartssekvensen som standard. Med `versionNegotiation: { mode: 'auto' }` prøver klienten den nye flyten og kan falle tilbake til en eldre server. Med `versionNegotiation: { mode: { pin: '2026-07-28' } }` avvises forbindelsen hvis serveren ikke tilbyr den revisjonen. `getProtocolEra()` viser om forbindelsen endte som `modern` eller `legacy`.

På serversiden brukes `createMcpHandler` for HTTP eller `serveStdio` for stdio når den nye revisjonen skal tilbys. En server som fortsatt kobles direkte til `StdioServerTransport`, skifter ikke protokollflyt bare fordi SDK-pakken oppgraderes. Dette er et eget migreringssteg; auth-valgene nedenfor gjelder i SDK-en uavhengig av hvilken protokollflyt forbindelsen bruker.

Fire valg i OAuth-implementasjonen

SDK-ens v2-guide for auth beskriver API-ene, lagringsansvaret og feiltypene. Gå gjennom disse punktene i klienten og dens `OAuthClientProvider`:

1. Send og valider «iss». Les `state`, `code` og `iss` fra tilbakekalls-URL-en. Sammenlign selv `state` med verdien som ble lagret før omdirigeringen; SDK-en gjør ikke den kontrollen. Send deretter `URLSearchParams` til `transport.finishAuth()`, eller bruk `finishAuth(code, iss)`. Et «iss» som ikke stemmer med den validerte utstederen, gir `IssuerMismatchError` før kodeutveksling. Manglende «iss» avvises når autorisasjonsserveren har annonsert støtte for parameteren. Ikke vis `error`-felter fra et tilbakekall som feilet utstedervalideringen.
2. Bevar utstederen på legitimasjoner. Lagre `issuer`-feltet som SDK-en legger på verdier sendt til `saveTokens()` og `saveClientInformation()`, og returner hele feltet ved lesing. Hvis lagringskoden bygger nye objekter og utelater `issuer`, kan legitimasjonen fortsatt leses, mens kontrollen mot feil autorisasjonsserver uteblir. Ett lagringsspor er tilstrekkelig når feltet bevares; skal flere autorisasjonsservere ha legitimasjoner samtidig, kan lagringen nøstes etter `ctx.issuer`. For statisk konfigurerte legitimasjoner brukes `expectedIssuer`.
3. Lagre discovery state. Implementer både `saveDiscoveryState()` og `discoveryState()` i `OAuthClientProvider`. Tilstanden må overleve omstart på samme måte som `codeVerifier`, slik at tilbakekallet kan sammenholdes med autorisasjonsserveren brukeren ble sendt til. Hvis ny discovery peker på en annen server, skal flyten stoppe med `AuthorizationServerMismatchError` før koden veksles inn. Uten metodene gir SDK-en en advarsel, men applikasjonen får ikke denne kontrollen på tvers av tilbakekallet.
4. Velg håndtering av manglende scope. `StreamableHTTPClientTransport` bruker `onInsufficientScope: 'reauthorize'` som standard. Ved en `403`-utfordring med `insufficient_scope` samler SDK-en tidligere etterspurt scope og scope fra utfordringen; hvis dette går utover tokenets innvilgede rettigheter, starter den en ny autorisasjonsforespørsel. Velg `onInsufficientScope: 'throw'` når applikasjonen selv skal styre samtykket, eller når en maskin-til-maskin-klient ikke kan utvide rettighetene gjennom en brukerflyt. Håndter da transportens `InsufficientScopeError`, som er en annen feiltype enn `OAuthError` med koden `InsufficientScope`.

Før og etter i en eksisterende klient

Før migrering kan tilbakekallet sende bare `code` til `finishAuth()`, mens lagringskoden kopierer tokenfelter til ett objekt uten `issuer`. Etter migrering kontrollerer vertsapplikasjonen `state`, sender også `iss` og lagrer token og klientinformasjon med utstederfeltet intakt. Discovery state følger det samme autorisasjonsforsøket gjennom et eventuelt omstartet klientløp.

Det er to ulike utstederkontroller. `iss` i tilbakekallet sammenlignes med utstederen fra validerte metadata før kodeutveksling. Det lagrede `issuer`-feltet hindrer senere gjenbruk av legitimasjon mot en annen autorisasjonsserver. En klient som bare legger til `iss` i tilbakekallet, mangler fortsatt den siste kontrollen dersom lagringslaget kaster feltet.

Serverrespons og feil som påvirker flyten

Scope-opptrapping forutsetter at den beskyttede ressursen svarer med en `WWW-Authenticate`-utfordring som angir `insufficient_scope` og hvilke rettigheter som kreves. En vanlig `403` uten denne utfordringen gir ikke klienten samme grunnlag for ny autorisasjon. I en server som flyttes til v2, må tokenverifikatoren dessuten bruke v2-typen `OAuthError` for ugyldige token; en gammel feilklasse kan ellers bli behandlet som en uventet serverfeil.

Tokenendepunktet må bruke TLS utenfor lokale loopback-adresser. SDK-en avviser usikre eksterne tokenendepunkter med `InsecureTokenEndpointError`, mens fortrolig lagring av oppdateringstokener fortsatt er implementasjonens ansvar. For klienter med dynamisk registrering bør også `application_type` passe omdirigeringsadressen, særlig ved lokale omdirigeringer i skrivebords- og kommandolinjeprogrammer.

Kontrolliste før utrulling

• Test et tilbakekall med feil `state` og et eget med feil `iss`. Det første skal stoppes av applikasjonen; det andre skal gi `IssuerMismatchError` før kodeutveksling.
• Lagre legitimasjon fra én autorisasjonsserver og gjennomfør discovery mot en annen. Kontroller at klienten ikke gjenbruker token eller klientinformasjon fra den første serveren.
• Start autorisasjon, lagre discovery state og fullfør tilbakekallet etter omstart. Endre deretter den oppdagede autorisasjonsserveren i et kontrollert testløp og kontroller at koden ikke veksles inn.
• La en beskyttet operasjon kreve mer scope enn tokenet har. Kontroller ny autorisasjon med samlet scope, eller at `InsufficientScopeError` når applikasjonens egen håndtering dersom du har valgt `throw`.
• Kontroller protokollflyten separat med `getProtocolEra()`. En moderne protokollforbindelse erstatter ingen av kontrollene i OAuth-tilbakekallet eller lagringslaget.