all: client side OAuth support (#785)

This PR introduces client-side OAuth support.

# Overall design philosophy

The main new interface introduced to support client-side OAuth is the
`OAuthHandler`. Contrary to its counter-parts in some other SDKs, it is
intentionally small and generic so that it can support most of the OAuth
authorization flow variants. The main `mcp` package purposefully
delegates almost all auth handling to `OAuthHandler` implementations.
This way, the `mcp` package continues to be largely OAuth agnostic.

The `auth` package comes with a default `OAuthHandler` implementation –
`AuthorizationCodeHandler`, which implements the authorization flow
for the `authorization_code` grant type, as defined in the [MCP
specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
It is expected that the `OAuthHandler` implementation granularity will
be roughly per grant type, as this parameter influences the
authorization flow the most.

# Detailed design

## `OAuthHandler` (auth/client.go)

The main interface for the integration consists of two methods:

```go
type OAuthHandler interface {
	// TokenSource returns a token source to be used for outgoing requests.
	// Returned token source might be nil. In that case, the transport will not
	// add any authorization headers to the request.
	TokenSource(context.Context) (oauth2.TokenSource, error)

	// Authorize is called when an HTTP request results in an error that may
	// be addressed by the authorization flow (currently 401 Unauthorized and 403 Forbidden).
	// It is responsible for performing the OAuth flow to obtain an access token.
	// The arguments are the request that failed and the response that was received for it.
	// The headers of the request are available, but the body will have already been consumed
	// when Authorize is called.
	// If the returned error is nil, TokenSource is expected to return a non-nil token source.
	// After a successful call to Authorize, the HTTP request will be retried by the transport.
	// The function is responsible for closing the response body.
	Authorize(context.Context, *http.Request, *http.Response) error
}
```

`StreamableClientTransport` accepts this interface as a field and uses
the `TokenSource` method to add an `Authorization: Bearer` header to
outgoing requests to the MCP server. If the request fails with `401:
Unauthorized` or `403: Forbidden`, the transport calls `Authorize` to
perform the authorization flow. If `Authorize` returns a non-nil error,
the request is retried once. `Authorize` errors do not result in
termination of the client session (unless they happen during
connection initialization), as some OAuth flows are multi-legged and it should be
acceptable to retry for example when the authorization grant was
received.

*Note:* There was already an `OAuthHandler` type defined as part of a
previous iteration of OAuth support. It was renamed to
`OAuthHandlerLegacy`. This is the only backwards incompatible API change
in the experimental client `auth` part (protected by the
`mcp_go_client_oauth` Go build tag). The cost of replacing previous
usages is deemed worthwhile to maintain clear naming, under the
assumption that the experimental client `auth` part was not widely used.

## `AuthorizationCodeHandler` (auth/authorization_code.go)

This is the `OAuthHandler` implementation that fulfills the [MCP
specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
In particular, in supports:

- Protected Resource Metadata discovery and fetching
- Authorization Server Metadata discovery and fetching
- Client registration
  - OpenID Connect metadata document
  - Pre-registration
  - Dynamic Client Registration
- PKCE
- `client_secret_post`, `client_secret_basic` token endpoint
auth methods
- Automatic refresh of tokens

### Authorization Server redirect

As part of the flow for the `authorization_code` grant type, the client
needs to point the user to the authorization URL, so that they confirm
the access request. This design proposes that it will be supported via a
pluggable dependency that will initiate this process in an
application-specific way:

```go
type AuthorizationCodeHandler struct {
	...

	// AuthorizationCodeFetcher is a required function called to initiate the authorization flow.
	// It is responsible for opening the URL in a browser for the user to start the authorization process.
	// It should return the authorization code and state once the Authorization Server
	// redirects back to the RedirectURL.
	AuthorizationCodeFetcher func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error)

	...
}
```

The function is supposed perform any application specific logic to handle the redirect
from the Authorization Server and return the resulting code and state.

## `oauthex` changes

Some additional/adjusted building blocks that may be useful when
creating `OAuthHandler` implementations are present in the `oauthex`
package:

- `auth_meta.go`: Authorization Server Metadata utilities:
  - `GetAuthServerMeta`: get Authorization Server Metadata from a URL
- `dcr.go`: Dynamic Client Registration utilities (unchanged)
- `resource_meta.go`: Protected Resource Metadata utilities:
- `GetProtectedResourceMetadata`: get Protected Resource Metadata from a
URL
  - `ParseWWWAuthenticate` – as per name (unchanged)
- [deprecated] `GetProtectedResourceMetadataFromID` and
`GetProtectedResourceMetadataFromHeader` in favor of more generic
`GetProtectedResourceMetadata`. They will be kept under the Go build tag
and removed one version of the SDK in the future.

examples/auth/client/main.go

@@ -0,0 +1,130 @@
+// Copyright 2026 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by the license
+// that can be found in the LICENSE file.
+
+//go:build mcp_go_client_oauth
+
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+
+	"github.com/modelcontextprotocol/go-sdk/auth"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+var (
+	// URL of the MCP server.
+	serverURL = flag.String("server_url", "http://localhost:8000/mcp", "URL of the MCP server.")
+	// Port for the local HTTP server that will receive the authorization code.
+	callbackPort = flag.Int("callback_port", 3142, "Port for the local HTTP server that will receive the authorization code.")
+)
+
+type codeReceiver struct {
+	authChan chan *auth.AuthorizationResult
+	errChan  chan error
+	listener net.Listener
+	server   *http.Server
+}
+
+func (r *codeReceiver) serveRedirectHandler(listener net.Listener) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
+		r.authChan <- &auth.AuthorizationResult{
+			Code:  req.URL.Query().Get("code"),
+			State: req.URL.Query().Get("state"),
+		}
+		fmt.Fprint(w, "Authentication successful. You can close this window.")
+	})
+
+	r.server = &http.Server{
+		Addr:    fmt.Sprintf("localhost:%d", *callbackPort),
+		Handler: mux,
+	}
+	if err := r.server.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
+		r.errChan <- err
+	}
+}
+
+func (r *codeReceiver) getAuthorizationCode(ctx context.Context, args *auth.AuthorizationArgs) (*auth.AuthorizationResult, error) {
+	select {
+	case authRes := <-r.authChan:
+		return authRes, nil
+	case err := <-r.errChan:
+		return nil, err
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+}
+
+func (r *codeReceiver) close() {
+	if r.server != nil {
+		r.server.Close()
+	}
+}
+
+func main() {
+	flag.Parse()
+	receiver := &codeReceiver{
+		authChan: make(chan *auth.AuthorizationResult),
+		errChan:  make(chan error),
+	}
+	listener, err := net.Listen("tcp", fmt.Sprintf("localhost:%d", *callbackPort))
+	if err != nil {
+		log.Fatalf("failed to listen: %v", err)
+	}
+	go receiver.serveRedirectHandler(listener)
+	defer receiver.close()
+
+	authHandler, err := auth.NewAuthorizationCodeHandler(&auth.AuthorizationCodeHandlerConfig{
+		RedirectURL:              fmt.Sprintf("http://localhost:%d", *callbackPort),
+		AuthorizationCodeFetcher: receiver.getAuthorizationCode,
+		// Uncomment the client configuration you want to use.
+		// PreregisteredClientConfig: &auth.PreregisteredClientConfig{
+		// 	ClientID:     "",
+		// 	ClientSecret: "",
+		// },
+		// DynamicClientRegistrationConfig: &auth.DynamicClientRegistrationConfig{
+		// 	Metadata: &oauthex.ClientRegistrationMetadata{
+		// 		ClientName: "Dynamically registered MCP client",
+		// 		RedirectURIs: []string{fmt.Sprintf("http://localhost:%d", *callbackPort)},
+		// 		Scope: "read",
+		// 	},
+		// },
+	})
+	if err != nil {
+		log.Fatalf("failed to create auth handler: %v", err)
+	}
+
+	transport := &mcp.StreamableClientTransport{
+		Endpoint:     *serverURL,
+		OAuthHandler: authHandler,
+	}
+
+	ctx := context.Background()
+	client := mcp.NewClient(&mcp.Implementation{
+		Name:    "test-client",
+		Version: "1.0.0",
+	}, nil)
+
+	session, err := client.Connect(ctx, transport, nil)
+	if err != nil {
+		log.Fatalf("client.Connect(): %v", err)
+	}
+	defer session.Close()
+
+	tools, err := session.ListTools(ctx, nil)
+	if err != nil {
+		log.Fatalf("session.ListTools(): %v", err)
+	}
+	log.Println("Tools:")
+	for _, tool := range tools.Tools {
+		log.Printf("- %q", tool.Name)
+	}
+}