Merge branch 'v1.x' into claude/oauth-tokens-null-fields-v1x

Resolves conflicts with the #2888 issuer-binding backport, which added
a client-only issuer member to OAuthTokensSchema and parsed wire
responses through local OAuthTokensSchema.omit({ issuer: true })
schemas. The resolution folds that omission into
OAuthTokenResponseSchema itself: the exported wrapper now validates
against the issuer-less wire shape, so an authorization server can
neither slip null-valued optional members past validation nor inject
the issuer value the client binds stored credentials to. The three
parse sites (executeTokenRequest and both proxy provider exchanges)
keep using OAuthTokenResponseSchema, and the now-redundant local
TokenResponseSchema constants are removed. The exported
OAuthTokensSchema remains byte-identical to v1.x. Both test additions
are kept: this branch's null-optional-field proxy provider suite and
v1.x's issuer-forwarding rejection cases.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KXnNnp3fxQYR5HF9BUVhYP

Author: claude

.changeset/bind-oauth-credentials-to-issuer.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Bind stored OAuth client credentials to the authorization server that issued them. `auth()` adds an `issuer` property to what it passes to `saveClientInformation()` / `saveTokens()` and does not reuse a stored value with a different authorization server: the client registers or
+authorizes again, or `auth()` throws when the credentials cannot be re-created by registering. `OAuthTokensSchema` and `OAuthClientInformationSchema` accept the optional `issuer`. `ClientCredentialsProvider`, `PrivateKeyJwtProvider` and `StaticPrivateKeyJwtProvider` accept
+`expectedIssuer`; omitting it is deprecated.

.changeset/fix-oauth-resource-trailing-slash.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Preserve the exact OAuth resource indicator from protected resource metadata when building authorization and token requests. Previously a pathless `resource` such as `https://example.com` was normalized to `https://example.com/` via `URL.href`, which breaks authorization servers
+that require the `resource` parameter to match the published value exactly (Microsoft Entra ID rejects it with `AADSTS9010010`). The exported OAuth helpers (`startAuthorization`, `exchangeAuthorization`, `refreshAuthorization`, `fetchToken`) now also accept a `string` for
+`resource`; `selectResourceURL` still returns a `URL`, and a provider's `validateResourceURL` result is used unchanged. Fixes #1968.

docs/client.md

@@ -46,6 +46,11 @@ For OAuth-secured MCP servers, the client `auth` module exposes:
 - `PrivateKeyJwtProvider`
 - `StaticPrivateKeyJwtProvider`
 
+Pass `expectedIssuer` (the issuer URL of the authorization server the credentials were registered with) to each of these. `auth()` then only presents the credentials to that authorization server and throws if the MCP server advertises a different one. Omitting it is deprecated.
+
+If you implement `OAuthClientProvider` yourself, store the objects passed to `saveClientInformation()` and `saveTokens()` unchanged: they carry an `issuer` property naming the authorization server they came from, and `auth()` does not reuse them with a different one. If
+`clientInformation()` returns pre-registered credentials, include `issuer` yourself.
+
 Examples:
 
 - [`simpleOAuthClient.ts`](../src/examples/client/simpleOAuthClient.ts)

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@modelcontextprotocol/sdk",
-    "version": "1.30.0",
+    "version": "1.30.1",
     "description": "Model Context Protocol implementation for TypeScript",
     "license": "MIT",
     "author": "Anthropic, PBC (https://anthropic.com)",

package.json

@@ -90,6 +90,24 @@ export function createPrivateKeyJwtAuth(options: {
     };
 }
 
+/**
+ * The `issuer` stamp for constructor-supplied client information. Omitting `expectedIssuer` is
+ * deprecated: nothing else says which authorization server such credentials belong to.
+ */
+function checkedExpectedIssuer(expectedIssuer: string | undefined): string | undefined {
+    if (expectedIssuer === undefined) {
+        // eslint-disable-next-line no-console
+        console.warn(
+            '[mcp-sdk] Omitting `expectedIssuer` is deprecated. Without it, the MCP server decides which authorization ' +
+                "server receives this client's credentials; pass your authorization server's issuer URL as " +
+                '`expectedIssuer` so they are only sent there.'
+        );
+    } else if (typeof expectedIssuer !== 'string' || !expectedIssuer) {
+        throw new Error("expectedIssuer must be the authorization server's issuer URL");
+    }
+    return expectedIssuer;
+}
+
 /**
  * Options for creating a ClientCredentialsProvider.
  */
@@ -113,6 +131,16 @@ export interface ClientCredentialsProviderOptions {
      * Space-separated scopes values requested by the client.
      */
     scope?: string;
+
+    /**
+     * The issuer URL of the authorization server these credentials were registered with.
+     * When set, `auth()` only presents them to that authorization server and throws if the
+     * MCP server advertises a different URL (one trailing slash aside).
+     *
+     * Omitting it is deprecated: the credentials then go to whichever authorization server
+     * the MCP server advertises first.
+     */
+    expectedIssuer?: string;
 }
 
 /**
@@ -124,7 +152,8 @@ export interface ClientCredentialsProviderOptions {
  * @example
  * const provider = new ClientCredentialsProvider({
  *   clientId: 'my-client',
- *   clientSecret: 'my-secret'
+ *   clientSecret: 'my-secret',
+ *   expectedIssuer: 'https://auth.example.com'
  * });
  *
  * const transport = new StreamableHTTPClientTransport(serverUrl, {
@@ -136,10 +165,14 @@ export class ClientCredentialsProvider implements OAuthClientProvider {
     private _clientInfo: OAuthClientInformation;
     private _clientMetadata: OAuthClientMetadata;
 
+    constructor(options: ClientCredentialsProviderOptions & { expectedIssuer: string });
+    /** @deprecated Pass `expectedIssuer` so the credentials are only sent to that authorization server. */
+    constructor(options: ClientCredentialsProviderOptions);
     constructor(options: ClientCredentialsProviderOptions) {
         this._clientInfo = {
             client_id: options.clientId,
-            client_secret: options.clientSecret
+            client_secret: options.clientSecret,
+            issuer: checkedExpectedIssuer(options.expectedIssuer)
         };
         this._clientMetadata = {
             client_name: options.clientName ?? 'client-credentials-client',
@@ -227,6 +260,16 @@ export interface PrivateKeyJwtProviderOptions {
      * Space-separated scopes values requested by the client.
      */
     scope?: string;
+
+    /**
+     * The issuer URL of the authorization server these credentials were registered with.
+     * When set, `auth()` only presents them to that authorization server and throws if the
+     * MCP server advertises a different URL (one trailing slash aside).
+     *
+     * Omitting it is deprecated: the credentials then go to whichever authorization server
+     * the MCP server advertises first.
+     */
+    expectedIssuer?: string;
 }
 
 /**
@@ -239,7 +282,8 @@ export interface PrivateKeyJwtProviderOptions {
  * const provider = new PrivateKeyJwtProvider({
  *   clientId: 'my-client',
  *   privateKey: pemEncodedPrivateKey,
- *   algorithm: 'RS256'
+ *   algorithm: 'RS256',
+ *   expectedIssuer: 'https://auth.example.com'
  * });
  *
  * const transport = new StreamableHTTPClientTransport(serverUrl, {
@@ -252,9 +296,13 @@ export class PrivateKeyJwtProvider implements OAuthClientProvider {
     private _clientMetadata: OAuthClientMetadata;
     addClientAuthentication: AddClientAuthentication;
 
+    constructor(options: PrivateKeyJwtProviderOptions & { expectedIssuer: string });
+    /** @deprecated Pass `expectedIssuer` so the credentials are only sent to that authorization server. */
+    constructor(options: PrivateKeyJwtProviderOptions);
     constructor(options: PrivateKeyJwtProviderOptions) {
         this._clientInfo = {
-            client_id: options.clientId
+            client_id: options.clientId,
+            issuer: checkedExpectedIssuer(options.expectedIssuer)
         };
         this._clientMetadata = {
             client_name: options.clientName ?? 'private-key-jwt-client',
@@ -341,6 +389,16 @@ export interface StaticPrivateKeyJwtProviderOptions {
      * Space-separated scopes values requested by the client.
      */
     scope?: string;
+
+    /**
+     * The issuer URL of the authorization server these credentials were registered with.
+     * When set, `auth()` only presents them to that authorization server and throws if the
+     * MCP server advertises a different URL (one trailing slash aside).
+     *
+     * Omitting it is deprecated: the credentials then go to whichever authorization server
+     * the MCP server advertises first.
+     */
+    expectedIssuer?: string;
 }
 
 /**
@@ -356,9 +414,13 @@ export class StaticPrivateKeyJwtProvider implements OAuthClientProvider {
     private _clientMetadata: OAuthClientMetadata;
     addClientAuthentication: AddClientAuthentication;
 
+    constructor(options: StaticPrivateKeyJwtProviderOptions & { expectedIssuer: string });
+    /** @deprecated Pass `expectedIssuer` so the credentials are only sent to that authorization server. */
+    constructor(options: StaticPrivateKeyJwtProviderOptions);
     constructor(options: StaticPrivateKeyJwtProviderOptions) {
         this._clientInfo = {
-            client_id: options.clientId
+            client_id: options.clientId,
+            issuer: checkedExpectedIssuer(options.expectedIssuer)
         };
         this._clientMetadata = {
             client_name: options.clientName ?? 'static-private-key-jwt-client',