modelcontextprotocol/go-sdk
Watch
1
0
Fork
You've already forked go-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

all: client side OAuth support (#785)

Browse source 
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.
This commit is contained in:
Maciej Kisiel 2026-02-27 15:30:13 +01:00 • committed by GitHub
commit c9317fb5b7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
29 changed files with 2743 additions and 434 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/conformance.yml vendored
View file

@ -50,7 +50,7 @@ jobs:
uses: modelcontextprotocol/conformance@a2855b03582a6c0b31065ad4d9af248316ce61a3 # v0.1.15
with:
mode: client
command: go run ./conformance/everything-client/main.go
command: go run -tags mcp_go_client_oauth ./conformance/everything-client
suite: core
expected-failures: ./conformance/baseline.yml
node-version: 22

13
README.md
View file

@ -34,10 +34,15 @@ contains feature documentation, mapping the MCP spec to the packages above.
The following table shows which versions of the Go SDK support which versions of the MCP specification:
| SDK Version | Latest MCP Spec | All Supported MCP Specs |
|-----------------|-------------------|------------------------------------------------|
| v1.2.0+ | 2025-06-18 | 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 |
| v1.0.0 - v1.1.0 | 2025-06-18 | 2025-06-18, 2025-03-26, 2024-11-05 |
| SDK Version | Latest MCP Spec | All Supported MCP Specs |
|-----------------|-------------------|----------------------------------------------------|
| v1.4.0+ | 2025-11-25\* | 2025-11-25\*, 2025-06-18, 2025-03-26, 2024-11-05 |
| v1.2.0 - v1.3.1 | 2025-11-25\*\* | 2025-11-25\*\*, 2025-06-18, 2025-03-26, 2024-11-05 |
| v1.0.0 - v1.1.0 | 2025-06-18 | 2025-06-18, 2025-03-26, 2024-11-05 |
\* Client side OAuth has experimental support.
\*\* Partial support for 2025-11-25 (client side OAuth and Sampling with tools not available).
New releases of the SDK target only supported versions of Go. See
https://go.dev/doc/devel/release#policy for more information.

6
auth/auth.go
View file

@ -25,8 +25,7 @@ type TokenInfo struct {
// session hijacking by ensuring that all requests for a given session
// come from the same user.
UserID string
// TODO: add standard JWT fields
Extra map[string]any
Extra map[string]any
}
// The error that a TokenVerifier should return if the token cannot be verified.
@ -106,6 +105,9 @@ func verify(req *http.Request, verifier TokenVerifier, opts *RequireBearerTokenO
}
return nil, err.Error(), http.StatusInternalServerError
}
if tokenInfo == nil {
return nil, "token validation failed", http.StatusInternalServerError
}
// Check scopes. All must be present.
if opts != nil {

548
auth/authorization_code.go Normal file
View file

@ -0,0 +1,548 @@
// 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 auth
import (
"context"
"crypto/rand"
"errors"
"fmt"
"net/http"
"net/url"
"slices"
"strings"
"github.com/modelcontextprotocol/go-sdk/oauthex"
"golang.org/x/oauth2"
)
// ClientSecretAuthConfig is used to configure client authentication using client_secret.
// Authentication method will be selected based on the authorization server's supported methods,
// according to the following preference order:
// 1. client_secret_post
// 2. client_secret_basic
type ClientSecretAuthConfig struct {
// ClientID is the client ID to be used for client authentication.
ClientID string
// ClientSecret is the client secret to be used for client authentication.
ClientSecret string
}
// ClientIDMetadataDocumentConfig is used to configure the Client ID Metadata Document
// based client registration per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents.
// See https://client.dev/ for more information.
type ClientIDMetadataDocumentConfig struct {
// URL is the client identifier URL as per
// https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00#section-3.
URL string
}
// PreregisteredClientConfig is used to configure a pre-registered client per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#preregistration.
// Currently only "client_secret_basic" and "client_secret_post" authentication methods are supported.
type PreregisteredClientConfig struct {
// ClientSecretAuthConfig is the client_secret based configuration to be used for client authentication.
ClientSecretAuthConfig *ClientSecretAuthConfig
}
// DynamicClientRegistrationConfig is used to configure dynamic client registration per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration.
type DynamicClientRegistrationConfig struct {
// Metadata to be used in dynamic client registration request as per
// https://datatracker.ietf.org/doc/html/rfc7591#section-2.
Metadata *oauthex.ClientRegistrationMetadata
}
// AuthorizationResult is the result of an authorization flow.
// It is returned by [AuthorizationCodeHandler].AuthorizationCodeFetcher implementations.
type AuthorizationResult struct {
// Code is the authorization code obtained from the authorization server.
Code string
// State string returned by the authorization server.
State string
}
// AuthorizationArgs is the input to [AuthorizationCodeHandlerConfig].AuthorizationCodeFetcher.
type AuthorizationArgs struct {
// Authorization URL to be opened in a browser for the user to start the authorization process.
URL string
}
// AuthorizationCodeHandlerConfig is the configuration for [AuthorizationCodeHandler].
type AuthorizationCodeHandlerConfig struct {
// Client registration configuration.
// It is attempted in the following order:
// 1. Client ID Metadata Document
// 2. Preregistration
// 3. Dynamic Client Registration
// At least one method must be configured.
ClientIDMetadataDocumentConfig *ClientIDMetadataDocumentConfig
PreregisteredClientConfig *PreregisteredClientConfig
DynamicClientRegistrationConfig *DynamicClientRegistrationConfig
// RedirectURL is a required URL to redirect to after authorization.
// The caller is responsible for handling the redirect out of band.
//
// If Dynamic Client Registration is used:
// - this field is permitted to be empty, in which case it will be set
// to the first redirect URI from
// DynamicClientRegistrationConfig.Metadata.RedirectURIs.
// - if the field is not empty, it must be one of the redirect URIs in
// DynamicClientRegistrationConfig.Metadata.RedirectURIs.
RedirectURL string
// 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)
}
// AuthorizationCodeHandler is an implementation of [OAuthHandler] that uses
// the authorization code flow to obtain access tokens.
type AuthorizationCodeHandler struct {
config *AuthorizationCodeHandlerConfig
// tokenSource is the token source to use for authorization.
tokenSource oauth2.TokenSource
}
var _ OAuthHandler = (*AuthorizationCodeHandler)(nil)
func (h *AuthorizationCodeHandler) isOAuthHandler() {}
func (h *AuthorizationCodeHandler) TokenSource(ctx context.Context) (oauth2.TokenSource, error) {
return h.tokenSource, nil
}
// NewAuthorizationCodeHandler creates a new AuthorizationCodeHandler.
// It performs validation of the configuration and returns an error if it is invalid.
// The passed config is consumed by the handler and should not be modified after.
func NewAuthorizationCodeHandler(config *AuthorizationCodeHandlerConfig) (*AuthorizationCodeHandler, error) {
if config == nil {
return nil, errors.New("config must be provided")
}
if config.ClientIDMetadataDocumentConfig == nil &&
config.PreregisteredClientConfig == nil &&
config.DynamicClientRegistrationConfig == nil {
return nil, errors.New("at least one client registration configuration must be provided")
}
if config.AuthorizationCodeFetcher == nil {
return nil, errors.New("AuthorizationCodeFetcher is required")
}
if config.ClientIDMetadataDocumentConfig != nil && !isNonRootHTTPSURL(config.ClientIDMetadataDocumentConfig.URL) {
return nil, fmt.Errorf("client ID metadata document URL must be a non-root HTTPS URL")
}
preCfg := config.PreregisteredClientConfig
if preCfg != nil {
if preCfg.ClientSecretAuthConfig == nil {
return nil, errors.New("ClientSecretAuthConfig is required for pre-registered client")
}
if preCfg.ClientSecretAuthConfig.ClientID == "" || preCfg.ClientSecretAuthConfig.ClientSecret == "" {
return nil, fmt.Errorf("pre-registered client ID or secret is empty")
}
}
dCfg := config.DynamicClientRegistrationConfig
if dCfg != nil {
if dCfg.Metadata == nil {
return nil, errors.New("Metadata is required for dynamic client registration")
}
if len(dCfg.Metadata.RedirectURIs) == 0 {
return nil, errors.New("Metadata.RedirectURIs is required for dynamic client registration")
}
if config.RedirectURL == "" {
config.RedirectURL = dCfg.Metadata.RedirectURIs[0]
} else if !slices.Contains(dCfg.Metadata.RedirectURIs, config.RedirectURL) {
return nil, fmt.Errorf("RedirectURL %q is not in the list of allowed redirect URIs for dynamic client registration", config.RedirectURL)
}
}
if config.RedirectURL == "" {
// If the RedirectURL was supposed to be set by the dynamic client registration,
// it should have been set by now. Otherwise, it is required.
return nil, errors.New("RedirectURL is required")
}
return &AuthorizationCodeHandler{config: config}, nil
}
func isNonRootHTTPSURL(u string) bool {
pu, err := url.Parse(u)
if err != nil {
return false
}
return pu.Scheme == "https" && pu.Path != ""
}
// Authorize performs the authorization flow.
// It is designed to perform the whole Authorization Code Grant flow.
// On success, [AuthorizationCodeHandler.TokenSource] will return a token source with the fetched token.
func (h *AuthorizationCodeHandler) Authorize(ctx context.Context, req *http.Request, resp *http.Response) error {
defer resp.Body.Close()
wwwChallenges, err := oauthex.ParseWWWAuthenticate(resp.Header[http.CanonicalHeaderKey("WWW-Authenticate")])
if err != nil {
return fmt.Errorf("failed to parse WWW-Authenticate header: %v", err)
}
if resp.StatusCode == http.StatusForbidden && errorFromChallenges(wwwChallenges) != "insufficient_scope" {
// We only want to perform step-up authorization for insufficient_scope errors.
// Returning nil, so that the call is retried immediately and the response
// is handled appropriately by the connection.
// Step-up authorization is defined at
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#step-up-authorization-flow
return nil
}
prm, err := h.getProtectedResourceMetadata(ctx, wwwChallenges, req.URL.String())
if err != nil {
return err
}
asm, err := h.getAuthServerMetadata(ctx, prm)
if err != nil {
return err
}
resolvedClientConfig, err := h.handleRegistration(ctx, asm)
if err != nil {
return err
}
scps := scopesFromChallenges(wwwChallenges)
if len(scps) == 0 && len(prm.ScopesSupported) > 0 {
scps = prm.ScopesSupported
}
cfg := &oauth2.Config{
ClientID: resolvedClientConfig.clientID,
ClientSecret: resolvedClientConfig.clientSecret,
Endpoint: oauth2.Endpoint{
AuthURL: asm.AuthorizationEndpoint,
TokenURL: asm.TokenEndpoint,
AuthStyle: resolvedClientConfig.authStyle,
},
RedirectURL: h.config.RedirectURL,
Scopes: scps,
}
authRes, err := h.getAuthorizationCode(ctx, cfg, req.URL.String())
if err != nil {
// Purposefully leaving the error unwrappable so it can be handled by the caller.
return err
}
return h.exchangeAuthorizationCode(ctx, cfg, authRes, prm.Resource)
}
// resourceMetadataURLFromChallenges returns a resource metadata URL from the given "WWW-Authenticate" header challenges,
// or the empty string if there is none.
func resourceMetadataURLFromChallenges(cs []oauthex.Challenge) string {
for _, c := range cs {
if u := c.Params["resource_metadata"]; u != "" {
return u
}
}
return ""
}
// scopesFromChallenges returns the scopes from the given "WWW-Authenticate" header challenges.
// It only looks at challenges with the "Bearer" scheme.
func scopesFromChallenges(cs []oauthex.Challenge) []string {
for _, c := range cs {
if c.Scheme == "bearer" && c.Params["scope"] != "" {
return strings.Fields(c.Params["scope"])
}
}
return nil
}
// errorFromChallenges returns the error from the given "WWW-Authenticate" header challenges.
// It only looks at challenges with the "Bearer" scheme.
func errorFromChallenges(cs []oauthex.Challenge) string {
for _, c := range cs {
if c.Scheme == "bearer" && c.Params["error"] != "" {
return c.Params["error"]
}
}
return ""
}
// getProtectedResourceMetadata returns the protected resource metadata.
// If no metadata was found or the fetched metadata fails security checks,
// it returns an error.
func (h *AuthorizationCodeHandler) getProtectedResourceMetadata(ctx context.Context, wwwChallenges []oauthex.Challenge, mcpServerURL string) (*oauthex.ProtectedResourceMetadata, error) {
var errs []error
// Use MCP server URL as the resource URI per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#canonical-server-uri.
for _, url := range protectedResourceMetadataURLs(resourceMetadataURLFromChallenges(wwwChallenges), mcpServerURL) {
prm, err := oauthex.GetProtectedResourceMetadata(ctx, url.URL, url.Resource, http.DefaultClient)
if err != nil {
errs = append(errs, err)
continue
}
if prm == nil {
errs = append(errs, fmt.Errorf("protected resource metadata is nil"))
continue
}
return prm, nil
}
return nil, fmt.Errorf("failed to get protected resource metadata: %v", errors.Join(errs...))
}
type prmURL struct {
// URL represents a URL where Protected Resource Metadata may be retrieved.
URL string
// Resource represents the corresponding resource URL for [URL].
// It is required to perform validation described in RFC 9728, section 3.3.
Resource string
}
// protectedResourceMetadataURLs returns a list of URLs to try when looking for
// protected resource metadata as mandated by the MCP specification:
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#protected-resource-metadata-discovery-requirements
func protectedResourceMetadataURLs(metadataURL, resourceURL string) []prmURL {
var urls []prmURL
if metadataURL != "" {
urls = append(urls, prmURL{
URL: metadataURL,
Resource: resourceURL,
})
}
ru, err := url.Parse(resourceURL)
if err != nil {
return urls
}
mu := *ru
// "At the path of the server's MCP endpoint".
mu.Path = "/.well-known/oauth-protected-resource/" + strings.TrimLeft(ru.Path, "/")
urls = append(urls, prmURL{
URL: mu.String(),
Resource: resourceURL,
})
// "At the root".
mu.Path = "/.well-known/oauth-protected-resource"
ru.Path = ""
urls = append(urls, prmURL{
URL: mu.String(),
Resource: ru.String(),
})
return urls
}
// getAuthServerMetadata returns the authorization server metadata.
// The provided Protected Resource Metadata must not be nil.
// It returns an error if the metadata request fails with non-4xx HTTP status code
// or the fetched metadata fails security checks.
// If no metadata was found, it returns a minimal set of endpoints
// as a fallback to 2025-03-26 spec.
func (h *AuthorizationCodeHandler) getAuthServerMetadata(ctx context.Context, prm *oauthex.ProtectedResourceMetadata) (*oauthex.AuthServerMeta, error) {
var authServerURL string
if len(prm.AuthorizationServers) > 0 {
// Use the first authorization server, similarly to other SDKs.
authServerURL = prm.AuthorizationServers[0]
} else {
// Fallback to 2025-03-26 spec: MCP server base URL acts as Authorization Server.
authURL, err := url.Parse(prm.Resource)
if err != nil {
return nil, fmt.Errorf("failed to parse resource URL: %v", err)
}
authURL.Path = ""
authServerURL = authURL.String()
}
for _, u := range authorizationServerMetadataURLs(authServerURL) {
asm, err := oauthex.GetAuthServerMeta(ctx, u, authServerURL, http.DefaultClient)
if err != nil {
return nil, fmt.Errorf("failed to get authorization server metadata: %w", err)
}
if asm != nil {
return asm, nil
}
}
// Fallback to 2025-03-26 spec: predefined endpoints.
// https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#fallbacks-for-servers-without-metadata-discovery
asm := &oauthex.AuthServerMeta{
Issuer: authServerURL,
AuthorizationEndpoint: authServerURL + "/authorize",
TokenEndpoint: authServerURL + "/token",
RegistrationEndpoint: authServerURL + "/register",
}
return asm, nil
}
// authorizationServerMetadataURLs returns a list of URLs to try when looking for
// authorization server metadata as mandated by the MCP specification:
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery.
func authorizationServerMetadataURLs(issuerURL string) []string {
var urls []string
baseURL, err := url.Parse(issuerURL)
if err != nil {
return nil
}
if baseURL.Path == "" {
// "OAuth 2.0 Authorization Server Metadata".
baseURL.Path = "/.well-known/oauth-authorization-server"
urls = append(urls, baseURL.String())
// "OpenID Connect Discovery 1.0".
baseURL.Path = "/.well-known/openid-configuration"
urls = append(urls, baseURL.String())
return urls
}
originalPath := baseURL.Path
// "OAuth 2.0 Authorization Server Metadata with path insertion".
baseURL.Path = "/.well-known/oauth-authorization-server/" + strings.TrimLeft(originalPath, "/")
urls = append(urls, baseURL.String())
// "OpenID Connect Discovery 1.0 with path insertion".
baseURL.Path = "/.well-known/openid-configuration/" + strings.TrimLeft(originalPath, "/")
urls = append(urls, baseURL.String())
// "OpenID Connect Discovery 1.0 with path appending".
baseURL.Path = "/" + strings.Trim(originalPath, "/") + "/.well-known/openid-configuration"
urls = append(urls, baseURL.String())
return urls
}
type registrationType int
const (
registrationTypeClientIDMetadataDocument registrationType = iota
registrationTypePreregistered
registrationTypeDynamic
)
type resolvedClientConfig struct {
registrationType registrationType
clientID string
clientSecret string
authStyle oauth2.AuthStyle
}
func selectTokenAuthMethod(supported []string) oauth2.AuthStyle {
prefOrder := []string{
// Preferred in OAuth 2.1 draft: https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-14.html#name-client-secret.
"client_secret_post",
"client_secret_basic",
}
for _, method := range prefOrder {
if slices.Contains(supported, method) {
return authMethodToStyle(method)
}
}
return oauth2.AuthStyleAutoDetect
}
func authMethodToStyle(method string) oauth2.AuthStyle {
switch method {
case "client_secret_post":
return oauth2.AuthStyleInParams
case "client_secret_basic":
return oauth2.AuthStyleInHeader
case "none":
// "none" is equivalent to "client_secret_post" but without sending client secret.
return oauth2.AuthStyleInParams
default:
// "client_secret_basic" is the default per https://datatracker.ietf.org/doc/html/rfc7591#section-2.
return oauth2.AuthStyleInHeader
}
}
// handleRegistration handles client registration.
// The provided authorization server metadata must be non-nil.
// Support for different registration methods is defined as follows:
// - Client ID Metadata Document: metadata must have
// `ClientIDMetadataDocumentSupported` set to true.
// - Pre-registered client: assumed to be supported.
// - Dynamic client registration: metadata must have
// `RegistrationEndpoint` set to a non-empty value.
func (h *AuthorizationCodeHandler) handleRegistration(ctx context.Context, asm *oauthex.AuthServerMeta) (*resolvedClientConfig, error) {
// 1. Attempt to use Client ID Metadata Document (SEP-991).
cimdCfg := h.config.ClientIDMetadataDocumentConfig
if cimdCfg != nil && asm.ClientIDMetadataDocumentSupported {
return &resolvedClientConfig{
registrationType: registrationTypeClientIDMetadataDocument,
clientID: cimdCfg.URL,
}, nil
}
// 2. Attempt to use pre-registered client configuration.
pCfg := h.config.PreregisteredClientConfig
if pCfg != nil {
authStyle := selectTokenAuthMethod(asm.TokenEndpointAuthMethodsSupported)
return &resolvedClientConfig{
registrationType: registrationTypePreregistered,
clientID: pCfg.ClientSecretAuthConfig.ClientID,
clientSecret: pCfg.ClientSecretAuthConfig.ClientSecret,
authStyle: authStyle,
}, nil
}
// 3. Attempt to use dynamic client registration.
dcrCfg := h.config.DynamicClientRegistrationConfig
if dcrCfg != nil && asm.RegistrationEndpoint != "" {
regResp, err := oauthex.RegisterClient(ctx, asm.RegistrationEndpoint, dcrCfg.Metadata, http.DefaultClient)
if err != nil {
return nil, fmt.Errorf("failed to register client: %w", err)
}
cfg := &resolvedClientConfig{
registrationType: registrationTypeDynamic,
clientID: regResp.ClientID,
clientSecret: regResp.ClientSecret,
authStyle: authMethodToStyle(regResp.TokenEndpointAuthMethod),
}
return cfg, nil
}
return nil, fmt.Errorf("no configured client registration methods are supported by the authorization server")
}
type authResult struct {
*AuthorizationResult
// usedCodeVerifier is the PKCE code verifier used to obtain the authorization code.
// It is preserved for the token exchange step.
usedCodeVerifier string
}
// getAuthorizationCode uses the [AuthorizationCodeHandler.AuthorizationCodeFetcher]
// to obtain an authorization code.
func (h *AuthorizationCodeHandler) getAuthorizationCode(ctx context.Context, cfg *oauth2.Config, resourceURL string) (*authResult, error) {
codeVerifier := oauth2.GenerateVerifier()
state := rand.Text()
authURL := cfg.AuthCodeURL(state,
oauth2.S256ChallengeOption(codeVerifier),
oauth2.SetAuthURLParam("resource", resourceURL),
)
authRes, err := h.config.AuthorizationCodeFetcher(ctx, &AuthorizationArgs{URL: authURL})
if err != nil {
// Purposefully leaving the error unwrappable so it can be handled by the caller.
return nil, err
}
if authRes.State != state {
return nil, fmt.Errorf("state mismatch")
}
return &authResult{
AuthorizationResult: authRes,
usedCodeVerifier: codeVerifier,
}, nil
}
// exchangeAuthorizationCode exchanges the authorization code for a token
// and stores it in a token source.
func (h *AuthorizationCodeHandler) exchangeAuthorizationCode(ctx context.Context, cfg *oauth2.Config, authResult *authResult, resourceURL string) error {
opts := []oauth2.AuthCodeOption{
oauth2.VerifierOption(authResult.usedCodeVerifier),
oauth2.SetAuthURLParam("resource", resourceURL),
}
token, err := cfg.Exchange(ctx, authResult.Code, opts...)
if err != nil {
return fmt.Errorf("token exchange failed: %w", err)
}
h.tokenSource = cfg.TokenSource(ctx, token)
return nil
}

658
auth/authorization_code_test.go Normal file
View file

@ -0,0 +1,658 @@
// 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 auth
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"net/http/httputil"
"testing"
"github.com/google/go-cmp/cmp"
"github.com/modelcontextprotocol/go-sdk/internal/oauthtest"
"github.com/modelcontextprotocol/go-sdk/oauthex"
"golang.org/x/oauth2"
)
func TestAuthorize(t *testing.T) {
authServer := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
RegistrationConfig: &oauthtest.RegistrationConfig{
PreregisteredClients: map[string]oauthtest.ClientInfo{
"test_client_id": {
Secret: "test_client_secret",
RedirectURIs: []string{"http://localhost:12345/callback"},
},
},
},
})
authServer.Start(t)
resourceMux := http.NewServeMux()
resourceServer := httptest.NewServer(resourceMux)
t.Cleanup(resourceServer.Close)
resourceURL := resourceServer.URL + "/resource"
resourceMux.Handle("/.well-known/oauth-protected-resource/resource", ProtectedResourceMetadataHandler(&oauthex.ProtectedResourceMetadata{
Resource: resourceURL,
AuthorizationServers: []string{authServer.URL()},
}))
handler, err := NewAuthorizationCodeHandler(&AuthorizationCodeHandlerConfig{
RedirectURL: "http://localhost:12345/callback",
PreregisteredClientConfig: &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "test_client_id",
ClientSecret: "test_client_secret",
},
},
AuthorizationCodeFetcher: func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
// The fake authorization server will redirect to an URL with code and state.
client := &http.Client{
CheckRedirect: func(req *http.Request, via []*http.Request) error {
return http.ErrUseLastResponse
},
}
resp, err := client.Get(args.URL)
if err != nil {
return nil, fmt.Errorf("failed to visit auth URL: %v", err)
}
defer resp.Body.Close()
dump, err := httputil.DumpResponse(resp, true)
if err != nil {
t.Fatalf("failed to dump response: %v", err)
}
t.Log(string(dump))
location, err := resp.Location()
if err != nil {
return nil, fmt.Errorf("failed to get location header: %v", err)
}
return &AuthorizationResult{
Code: location.Query().Get("code"),
State: location.Query().Get("state"),
}, nil
},
})
if err != nil {
t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
}
req := httptest.NewRequest(http.MethodGet, resourceURL, nil)
resp := &http.Response{
StatusCode: http.StatusUnauthorized,
Header: make(http.Header),
Body: http.NoBody,
Request: req,
}
resp.Header.Set(
"WWW-Authenticate",
"Bearer resource_metadata="+resourceServer.URL+"/.well-known/oauth-protected-resource/resource",
)
if err := handler.Authorize(context.Background(), req, resp); err != nil {
t.Fatalf("Authorize failed: %v", err)
}
tokenSource, err := handler.TokenSource(t.Context())
if err != nil {
t.Fatalf("Failed to get token source: %v", err)
}
token, err := tokenSource.Token()
if err != nil {
t.Fatalf("Failed to get token: %v", err)
}
if token.AccessToken != "test_access_token" {
t.Errorf("Expected access token 'test_access_token', got '%s'", token.AccessToken)
}
}
func TestAuthorize_ForbiddenUnhandledError(t *testing.T) {
req := httptest.NewRequest(http.MethodGet, "http://example.com/resource", nil)
resp := &http.Response{
StatusCode: http.StatusForbidden,
Header: make(http.Header),
Body: http.NoBody,
Request: req,
}
resp.Header.Set(
"WWW-Authenticate",
"Bearer error=invalid_token",
)
handler := &AuthorizationCodeHandler{} // No config needed for this test.
err := handler.Authorize(t.Context(), req, resp)
if err != nil {
t.Fatalf("Authorize() failed: %v", err)
}
}
func TestNewAuthorizationCodeHandler_Success(t *testing.T) {
simpleHandler := func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
return nil, nil
}
tests := []struct {
name string
config *AuthorizationCodeHandlerConfig
}{
{
name: "ClientIDMetadataDocumentConfig",
config: &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://example.com/client"},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: simpleHandler,
},
},
{
name: "PreregisteredClientConfig",
config: &AuthorizationCodeHandlerConfig{
PreregisteredClientConfig: &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "test_client_id",
ClientSecret: "test_client_secret",
},
},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: simpleHandler,
},
},
{
name: "DynamicClientRegistrationConfig_NoRedirectURL",
config: &AuthorizationCodeHandlerConfig{
DynamicClientRegistrationConfig: &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{
"https://example.com/callback",
},
},
},
AuthorizationCodeFetcher: simpleHandler,
},
},
{
name: "DynamicClientRegistrationConfig_WithRedirectURL",
config: &AuthorizationCodeHandlerConfig{
DynamicClientRegistrationConfig: &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{
"https://example.com/callback",
},
},
},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: simpleHandler,
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if _, err := NewAuthorizationCodeHandler(tt.config); err != nil {
t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
}
})
}
}
func TestNewAuthorizationCodeHandler_Error(t *testing.T) {
validConfig := func() *AuthorizationCodeHandlerConfig {
return &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://example.com/client"},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
return nil, nil
},
}
}
// Ensure the base config is valid
if _, err := NewAuthorizationCodeHandler(validConfig()); err != nil {
t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
}
tests := []struct {
name string
config func() *AuthorizationCodeHandlerConfig
}{
{
name: "NilConfig",
config: func() *AuthorizationCodeHandlerConfig {
return nil
},
},
{
name: "NoRegistrationConfig",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.ClientIDMetadataDocumentConfig = nil
cfg.PreregisteredClientConfig = nil
cfg.DynamicClientRegistrationConfig = nil
return cfg
},
},
{
name: "MissingRedirectURL",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.RedirectURL = ""
return cfg
},
},
{
name: "MissingAuthorizationCodeFetcher",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.AuthorizationCodeFetcher = nil
return cfg
},
},
{
name: "InvalidMetadataURL",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.ClientIDMetadataDocumentConfig.URL = "https://example.com"
return cfg
},
},
{
name: "InvalidPreregistered_MissingSecretConfig",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.PreregisteredClientConfig = &PreregisteredClientConfig{}
return cfg
},
},
{
name: "InvalidPreregistered_EmptyID",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.PreregisteredClientConfig = &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientSecret: "secret",
},
}
return cfg
},
},
{
name: "InvalidPreregistered_EmptySecret",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.PreregisteredClientConfig = &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "test_client_id",
},
}
return cfg
},
},
{
name: "InvalidDynamic_MissingMetadata",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.DynamicClientRegistrationConfig = &DynamicClientRegistrationConfig{}
return cfg
},
},
{
name: "InvalidDynamic_InconsistentRedirectURI",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.DynamicClientRegistrationConfig = &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{"https://example.com/callback1"},
},
}
cfg.RedirectURL = "https://example.com/callback2"
return cfg
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
_, err := NewAuthorizationCodeHandler(tt.config())
if err == nil {
t.Errorf("NewAuthorizationCodeHandler() = nil, want error")
}
})
}
}
func TestGetProtectedResourceMetadata(t *testing.T) {
handler := &AuthorizationCodeHandler{} // No config needed for this method
pathForChallenge := "/protected-resource"
tests := []struct {
name string
challengesProvided bool
prmPath string
resourcePath string
wantError bool
}{
{
name: "FromChallenges",
challengesProvided: true,
prmPath: pathForChallenge,
resourcePath: "/resource",
wantError: false,
},
{
name: "FallbackToEndpoint",
challengesProvided: false,
prmPath: "/.well-known/oauth-protected-resource/resource",
resourcePath: "/resource",
wantError: false,
},
{
name: "FallbackToRoot",
challengesProvided: false,
prmPath: "/.well-known/oauth-protected-resource",
resourcePath: "",
wantError: false,
},
{
name: "NoMetadata",
challengesProvided: false,
prmPath: "/incorrect",
wantError: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
mux := http.NewServeMux()
server := httptest.NewServer(mux)
t.Cleanup(server.Close)
resourceURL := server.URL + tt.resourcePath
metadata := &oauthex.ProtectedResourceMetadata{
Resource: resourceURL,
ScopesSupported: []string{"read", "write"},
}
mux.Handle(tt.prmPath, ProtectedResourceMetadataHandler(metadata))
var challenges []oauthex.Challenge
if tt.challengesProvided {
challenges = []oauthex.Challenge{
{
Scheme: "Bearer",
Params: map[string]string{
"resource_metadata": server.URL + pathForChallenge,
},
},
}
}
got, err := handler.getProtectedResourceMetadata(t.Context(), challenges, resourceURL)
if err != nil {
if !tt.wantError {
t.Fatalf("getProtectedResourceMetadata() error = %v, want nil", err)
}
return
}
if got == nil {
t.Fatal("getProtectedResourceMetadata() got nil, want metadata")
}
if diff := cmp.Diff(metadata, got); diff != "" {
t.Errorf("getProtectedResourceMetadata() metadata mismatch (-want +got):\n%s", diff)
}
})
}
}
func TestGetAuthServerMetadata(t *testing.T) {
handler := &AuthorizationCodeHandler{} // No config needed for this method
tests := []struct {
name string
authorizationAtMCPServer bool
issuerPath string
endpointConfig *oauthtest.MetadataEndpointConfig
}{
{
name: "OAuthEndpoint_Root",
authorizationAtMCPServer: false,
issuerPath: "",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOAuthInsertedEndpoint: true,
},
},
{
name: "OpenIDEndpoint_Root",
authorizationAtMCPServer: false,
issuerPath: "",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOpenIDInsertedEndpoint: true,
},
},
{
name: "OAuthEndpoint_Path",
authorizationAtMCPServer: false,
issuerPath: "/oauth",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOAuthInsertedEndpoint: true,
},
},
{
name: "OpenIDEndpoint_Path",
authorizationAtMCPServer: false,
issuerPath: "/openid",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOpenIDInsertedEndpoint: true,
},
},
{
name: "OpenIDAppendedEndpoint_Path",
authorizationAtMCPServer: false,
issuerPath: "/openid",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOpenIDAppendedEndpoint: true,
},
},
{
name: "FallbackToMCPServer",
authorizationAtMCPServer: true,
},
{
name: "NoMetadata",
issuerPath: "",
endpointConfig: &oauthtest.MetadataEndpointConfig{
// All metadata endpoints disabled.
ServeOAuthInsertedEndpoint: false,
ServeOpenIDInsertedEndpoint: false,
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
IssuerPath: tt.issuerPath,
MetadataEndpointConfig: tt.endpointConfig,
})
s.Start(t)
issuerURL := s.URL() + tt.issuerPath
resourceURL := "https://example.com/resource"
authServers := []string{issuerURL}
if tt.authorizationAtMCPServer {
resourceURL = issuerURL
authServers = nil
}
prm := &oauthex.ProtectedResourceMetadata{
Resource: resourceURL,
AuthorizationServers: authServers,
}
got, err := handler.getAuthServerMetadata(t.Context(), prm)
if err != nil {
t.Fatalf("getAuthServerMetadata() error = %v, want nil", err)
}
if got == nil {
t.Fatal("getAuthServerMetadata() got nil, want metadata")
}
if got.Issuer != issuerURL {
t.Errorf("getAuthServerMetadata() issuer = %q, want %q", got.Issuer, issuerURL)
}
})
}
}
func TestSelectTokenAuthMethod(t *testing.T) {
tests := []struct {
name string
supported []string
want oauth2.AuthStyle
}{
{
name: "PostPreferredOverBasic",
supported: []string{"client_secret_basic", "client_secret_post"},
want: oauth2.AuthStyleInParams,
},
{
name: "BasicChosenIfPostNotSupported",
supported: []string{"private_key_jwt", "client_secret_basic"},
want: oauth2.AuthStyleInHeader,
},
{
name: "NoneSupported",
supported: []string{"private_key_jwt"},
want: oauth2.AuthStyleAutoDetect,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := selectTokenAuthMethod(tt.supported)
if got != tt.want {
t.Errorf("selectTokenAuthMethod() = %v, want %v", got, tt.want)
}
})
}
}
func TestHandleRegistration(t *testing.T) {
tests := []struct {
name string
serverConfig *oauthtest.RegistrationConfig
handlerConfig *AuthorizationCodeHandlerConfig
asm *oauthex.AuthServerMeta
want *resolvedClientConfig
wantError bool
}{
{
name: "ClientIDMetadataDocument",
serverConfig: &oauthtest.RegistrationConfig{
ClientIDMetadataDocumentSupported: true,
},
handlerConfig: &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://client.example.com"},
},
want: &resolvedClientConfig{
registrationType: registrationTypeClientIDMetadataDocument,
clientID: "https://client.example.com",
},
},
{
name: "Preregistered",
serverConfig: &oauthtest.RegistrationConfig{
PreregisteredClients: map[string]oauthtest.ClientInfo{
"pre_client_id": {
Secret: "pre_client_secret",
},
},
},
handlerConfig: &AuthorizationCodeHandlerConfig{
PreregisteredClientConfig: &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "pre_client_id",
ClientSecret: "pre_client_secret",
},
},
},
want: &resolvedClientConfig{
registrationType: registrationTypePreregistered,
clientID: "pre_client_id",
clientSecret: "pre_client_secret",
authStyle: oauth2.AuthStyleInParams,
},
},
{
name: "NoneSupported",
handlerConfig: &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://client.example.com"},
},
wantError: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{RegistrationConfig: tt.serverConfig})
s.Start(t)
handler := &AuthorizationCodeHandler{config: tt.handlerConfig}
asm, err := handler.getAuthServerMetadata(t.Context(), &oauthex.ProtectedResourceMetadata{
AuthorizationServers: []string{s.URL()},
})
if err != nil {
t.Fatalf("getAuthServerMetadata() error = %v, want nil", err)
}
got, err := handler.handleRegistration(t.Context(), asm)
if err != nil {
if !tt.wantError {
t.Fatalf("handleRegistration() unexpected error = %v", err)
}
return
}
if got.registrationType != tt.want.registrationType {
t.Errorf("handleRegistration() registrationType = %v, want %v", got.registrationType, tt.want.registrationType)
}
if got.clientID != tt.want.clientID {
t.Errorf("handleRegistration() clientID = %q, want %q", got.clientID, tt.want.clientID)
}
if got.clientSecret != tt.want.clientSecret {
t.Errorf("handleRegistration() clientSecret = %q, want %q", got.clientSecret, tt.want.clientSecret)
}
if got.authStyle != tt.want.authStyle {
t.Errorf("handleRegistration() authStyle = %v, want %v", got.authStyle, tt.want.authStyle)
}
})
}
}
func TestDynamicRegistration(t *testing.T) {
s := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
RegistrationConfig: &oauthtest.RegistrationConfig{
DynamicClientRegistrationEnabled: true,
},
})
s.Start(t)
handler := &AuthorizationCodeHandler{config: &AuthorizationCodeHandlerConfig{
DynamicClientRegistrationConfig: &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{},
},
}}
asm, err := handler.getAuthServerMetadata(t.Context(), &oauthex.ProtectedResourceMetadata{
AuthorizationServers: []string{s.URL()},
})
if err != nil {
t.Fatalf("getAuthServerMetadata() error = %v, want nil", err)
}
got, err := handler.handleRegistration(t.Context(), asm)
if err != nil {
t.Fatalf("handleRegistration() error = %v, want nil", err)
}
if got.registrationType != registrationTypeDynamic {
t.Errorf("handleRegistration() registrationType = %v, want %v", got.registrationType, registrationTypeDynamic)
}
if got.clientID == "" {
t.Errorf("handleRegistration() clientID = %q, want non-empty", got.clientID)
}
if got.clientSecret == "" {
t.Errorf("handleRegistration() clientSecret = %q, want non-empty", got.clientSecret)
}
if got.authStyle != oauth2.AuthStyleInHeader {
t.Errorf("handleRegistration() authStyle = %v, want %v", got.authStyle, oauth2.AuthStyleInHeader)
}
}

137
auth/client.go
View file

@ -2,122 +2,41 @@
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package auth
import (
"bytes"
"errors"
"io"
"context"
"net/http"
"sync"
"golang.org/x/oauth2"
)
// An OAuthHandler conducts an OAuth flow and returns a [oauth2.TokenSource] if the authorization
// is approved, or an error if not.
// The handler receives the HTTP request and response that triggered the authentication flow.
// To obtain the protected resource metadata, call [oauthex.GetProtectedResourceMetadataFromHeader].
type OAuthHandler func(req *http.Request, res *http.Response) (oauth2.TokenSource, error)
// OAuthHandler is an interface for handling OAuth flows.
//
// If a transport wishes to support OAuth 2 authorization, it should support
// being configured with an OAuthHandler. It should call the handler's
// TokenSource method whenever it sends an HTTP request to set the
// Authorization header. If a request fails with a 401 or 403, it should call
// Authorize, and if that returns nil, it should retry the request. It should
// not call Authorize after the second failure. See
// [github.com/modelcontextprotocol/go-sdk/mcp.StreamableClientTransport]
// for an example.
type OAuthHandler interface {
isOAuthHandler()
// HTTPTransport is an [http.RoundTripper] that follows the MCP
// OAuth protocol when it encounters a 401 Unauthorized response.
type HTTPTransport struct {
handler OAuthHandler
mu sync.Mutex // protects opts.Base
opts HTTPTransportOptions
}
// NewHTTPTransport returns a new [*HTTPTransport].
// The handler is invoked when an HTTP request results in a 401 Unauthorized status.
// It is called only once per transport. Once a TokenSource is obtained, it is used
// for the lifetime of the transport; subsequent 401s are not processed.
func NewHTTPTransport(handler OAuthHandler, opts *HTTPTransportOptions) (*HTTPTransport, error) {
if handler == nil {
return nil, errors.New("handler cannot be nil")
}
t := &HTTPTransport{
handler: handler,
}
if opts != nil {
t.opts = *opts
}
if t.opts.Base == nil {
t.opts.Base = http.DefaultTransport
}
return t, nil
}
// HTTPTransportOptions are options to [NewHTTPTransport].
type HTTPTransportOptions struct {
// Base is the [http.RoundTripper] to use.
// If nil, [http.DefaultTransport] is used.
Base http.RoundTripper
}
func (t *HTTPTransport) RoundTrip(req *http.Request) (*http.Response, error) {
t.mu.Lock()
base := t.opts.Base
t.mu.Unlock()
var (
// If haveBody is set, the request has a nontrivial body, and we need avoid
// reading (or closing) it multiple times. In that case, bodyBytes is its
// content.
haveBody bool
bodyBytes []byte
)
if req.Body != nil && req.Body != http.NoBody {
// if we're setting Body, we must mutate first.
req = req.Clone(req.Context())
haveBody = true
var err error
bodyBytes, err = io.ReadAll(req.Body)
if err != nil {
return nil, err
}
// Now that we've read the request body, http.RoundTripper requires that we
// close it.
req.Body.Close() // ignore error
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
resp, err := base.RoundTrip(req)
if err != nil {
return nil, err
}
if resp.StatusCode != http.StatusUnauthorized {
return resp, nil
}
if _, ok := base.(*oauth2.Transport); ok {
// We failed to authorize even with a token source; give up.
return resp, nil
}
resp.Body.Close()
// Try to authorize.
t.mu.Lock()
defer t.mu.Unlock()
// If we don't have a token source, get one by following the OAuth flow.
// (We may have obtained one while t.mu was not held above.)
// TODO: We hold the lock for the entire OAuth flow. This could be a long
// time. Is there a better way?
if _, ok := t.opts.Base.(*oauth2.Transport); !ok {
ts, err := t.handler(req, resp)
if err != nil {
return nil, err
}
t.opts.Base = &oauth2.Transport{Base: t.opts.Base, Source: ts}
}
// If we don't have a body, the request is reusable, though it will be cloned
// by the base. However, if we've had to read the body, we must clone.
if haveBody {
req = req.Clone(req.Context())
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
return t.opts.Base.RoundTrip(req)
// 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
}

135
auth/client_private.go Normal file
View file

@ -0,0 +1,135 @@
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package auth
import (
"bytes"
"errors"
"io"
"net/http"
"sync"
"golang.org/x/oauth2"
)
// An OAuthHandlerLegacy conducts an OAuth flow and returns a [oauth2.TokenSource] if the authorization
// is approved, or an error if not.
// The handler receives the HTTP request and response that triggered the authentication flow.
// To obtain the protected resource metadata, call [oauthex.GetProtectedResourceMetadataFromHeader].
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
type OAuthHandlerLegacy func(req *http.Request, res *http.Response) (oauth2.TokenSource, error)
// HTTPTransport is an [http.RoundTripper] that follows the MCP
// OAuth protocol when it encounters a 401 Unauthorized response.
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
type HTTPTransport struct {
handler OAuthHandlerLegacy
mu sync.Mutex // protects opts.Base
opts HTTPTransportOptions
}
// NewHTTPTransport returns a new [*HTTPTransport].
// The handler is invoked when an HTTP request results in a 401 Unauthorized status.
// It is called only once per transport. Once a TokenSource is obtained, it is used
// for the lifetime of the transport; subsequent 401s are not processed.
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
func NewHTTPTransport(handler OAuthHandlerLegacy, opts *HTTPTransportOptions) (*HTTPTransport, error) {
if handler == nil {
return nil, errors.New("handler cannot be nil")
}
t := &HTTPTransport{
handler: handler,
}
if opts != nil {
t.opts = *opts
}
if t.opts.Base == nil {
t.opts.Base = http.DefaultTransport
}
return t, nil
}
// HTTPTransportOptions are options to [NewHTTPTransport].
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
type HTTPTransportOptions struct {
// Base is the [http.RoundTripper] to use.
// If nil, [http.DefaultTransport] is used.
Base http.RoundTripper
}
func (t *HTTPTransport) RoundTrip(req *http.Request) (*http.Response, error) {
t.mu.Lock()
base := t.opts.Base
t.mu.Unlock()
var (
// If haveBody is set, the request has a nontrivial body, and we need avoid
// reading (or closing) it multiple times. In that case, bodyBytes is its
// content.
haveBody bool
bodyBytes []byte
)
if req.Body != nil && req.Body != http.NoBody {
// if we're setting Body, we must mutate first.
req = req.Clone(req.Context())
haveBody = true
var err error
bodyBytes, err = io.ReadAll(req.Body)
if err != nil {
return nil, err
}
// Now that we've read the request body, http.RoundTripper requires that we
// close it.
req.Body.Close() // ignore error
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
resp, err := base.RoundTrip(req)
if err != nil {
return nil, err
}
if resp.StatusCode != http.StatusUnauthorized {
return resp, nil
}
if _, ok := base.(*oauth2.Transport); ok {
// We failed to authorize even with a token source; give up.
return resp, nil
}
resp.Body.Close()
// Try to authorize.
t.mu.Lock()
defer t.mu.Unlock()
// If we don't have a token source, get one by following the OAuth flow.
// (We may have obtained one while t.mu was not held above.)
// TODO: We hold the lock for the entire OAuth flow. This could be a long
// time. Is there a better way?
if _, ok := t.opts.Base.(*oauth2.Transport); !ok {
ts, err := t.handler(req, resp)
if err != nil {
return nil, err
}
t.opts.Base = &oauth2.Transport{Base: t.opts.Base, Source: ts}
}
// If we don't have a body, the request is reusable, though it will be cloned
// by the base. However, if we've had to read the body, we must clone.
if haveBody {
req = req.Clone(req.Context())
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
return t.opts.Base.RoundTrip(req)
}

20
conformance/baseline.yml
View file

@ -1,20 +1,2 @@
server: [] # All tests pass!
client:
- auth/basic-cimd
- auth/metadata-default
- auth/metadata-var1
- auth/metadata-var2
- auth/metadata-var3
- auth/2025-03-26-oauth-metadata-backcompat
- auth/2025-03-26-oauth-endpoint-fallback
- auth/scope-from-www-authenticate
- auth/scope-from-scopes-supported
- auth/scope-omitted-when-undefined
- auth/scope-step-up
- auth/scope-retry-limit
- auth/token-endpoint-auth-basic
- auth/token-endpoint-auth-post
- auth/token-endpoint-auth-none
- auth/client-credentials-jwt
- auth/client-credentials-basic
- auth/pre-registration
client: [] # All tests pass!

139
conformance/everything-client/client_private.go Normal file
View file

@ -0,0 +1,139 @@
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.
// The conformance client implements features required for MCP conformance testing.
// It mirrors the functionality of the TypeScript conformance client at
// https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/conformance/everything-client.ts
//go:build mcp_go_client_oauth
package main
import (
"context"
"fmt"
"net/http"
"net/url"
"github.com/modelcontextprotocol/go-sdk/auth"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/modelcontextprotocol/go-sdk/oauthex"
)
func init() {
authScenarios := []string{
"auth/2025-03-26-oauth-metadata-backcompat",
"auth/2025-03-26-oauth-endpoint-fallback",
"auth/basic-cimd",
"auth/metadata-default",
"auth/metadata-var1",
"auth/metadata-var2",
"auth/metadata-var3",
"auth/pre-registration",
"auth/resource-mismatch",
"auth/scope-from-www-authenticate",
"auth/scope-from-scopes-supported",
"auth/scope-omitted-when-undefined",
"auth/scope-step-up",
"auth/scope-retry-limit",
"auth/token-endpoint-auth-basic",
"auth/token-endpoint-auth-post",
"auth/token-endpoint-auth-none",
}
for _, scenario := range authScenarios {
registerScenario(scenario, runAuthClient)
}
}
// ============================================================================
// Auth scenarios
// ============================================================================
func fetchAuthorizationCodeAndState(ctx context.Context, args *auth.AuthorizationArgs) (*auth.AuthorizationResult, error) {
client := &http.Client{
CheckRedirect: func(req *http.Request, via []*http.Request) error {
return http.ErrUseLastResponse
},
}
req, err := http.NewRequestWithContext(ctx, "GET", args.URL, nil)
if err != nil {
return nil, err
}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// In conformance tests the authorization server immediately redirects
// to the callback URL with the authorization code and state.
locURL, err := url.Parse(resp.Header.Get("Location"))
if err != nil {
return nil, fmt.Errorf("parse location: %v", err)
}
return &auth.AuthorizationResult{
Code: locURL.Query().Get("code"),
State: locURL.Query().Get("state"),
}, nil
}
func runAuthClient(ctx context.Context, serverURL string, configCtx map[string]any) error {
authConfig := &auth.AuthorizationCodeHandlerConfig{
RedirectURL: "http://localhost:3000/callback",
AuthorizationCodeFetcher: fetchAuthorizationCodeAndState,
// Try client ID metadata document based registration.
ClientIDMetadataDocumentConfig: &auth.ClientIDMetadataDocumentConfig{
URL: "https://conformance-test.local/client-metadata.json",
},
// Try dynamic client registration.
DynamicClientRegistrationConfig: &auth.DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{"http://localhost:3000/callback"},
},
},
}
// Try pre-registered client information if provided in the context.
if clientID, ok := configCtx["client_id"].(string); ok {
if clientSecret, ok := configCtx["client_secret"].(string); ok {
authConfig.PreregisteredClientConfig = &auth.PreregisteredClientConfig{
ClientSecretAuthConfig: &auth.ClientSecretAuthConfig{
ClientID: clientID,
ClientSecret: clientSecret,
},
}
}
}
authHandler, err := auth.NewAuthorizationCodeHandler(authConfig)
if err != nil {
return fmt.Errorf("failed to create auth handler: %w", err)
}
session, err := connectToServer(ctx, serverURL, withOAuthHandler(authHandler))
if err != nil {
return err
}
defer session.Close()
if _, err := session.ListTools(ctx, nil); err != nil {
return fmt.Errorf("session.ListTools(): %v", err)
}
if _, err := session.CallTool(ctx, &mcp.CallToolParams{
Name: "test-tool",
Arguments: map[string]any{},
}); err != nil {
return fmt.Errorf("session.CallTool('test-tool'): %v", err)
}
return nil
}
func withOAuthHandler(handler auth.OAuthHandler) connectOption {
return func(c *connectConfig) {
c.oauthHandler = handler
}
}

34
conformance/everything-client/main.go
View file

@ -9,6 +9,7 @@ package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
@ -16,12 +17,13 @@ import (
"sort"
"strings"
"github.com/modelcontextprotocol/go-sdk/auth"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
// scenarioHandler is the function signature for all conformance test scenarios.
// It takes a context and the server URL to connect to.
type scenarioHandler func(ctx context.Context, serverURL string) error
type scenarioHandler func(ctx context.Context, serverURL string, configCtx map[string]any) error
var (
// registry stores all registered scenario handlers.
@ -48,7 +50,7 @@ func init() {
// Basic scenarios
// ============================================================================
func runBasicClient(ctx context.Context, serverURL string) error {
func runBasicClient(ctx context.Context, serverURL string, _ map[string]any) error {
session, err := connectToServer(ctx, serverURL)
if err != nil {
return err
@ -63,7 +65,7 @@ func runBasicClient(ctx context.Context, serverURL string) error {
return nil
}
func runToolsCallClient(ctx context.Context, serverURL string) error {
func runToolsCallClient(ctx context.Context, serverURL string, _ map[string]any) error {
session, err := connectToServer(ctx, serverURL)
if err != nil {
return err
@ -97,7 +99,7 @@ func runToolsCallClient(ctx context.Context, serverURL string) error {
// Elicitation scenarios
// ============================================================================
func runElicitationDefaultsClient(ctx context.Context, serverURL string) error {
func runElicitationDefaultsClient(ctx context.Context, serverURL string, _ map[string]any) error {
elicitationHandler := func(ctx context.Context, req *mcp.ElicitRequest) (*mcp.ElicitResult, error) {
return &mcp.ElicitResult{
Action: "accept",
@ -141,8 +143,7 @@ func runElicitationDefaultsClient(ctx context.Context, serverURL string) error {
// SSE retry scenario
// ============================================================================
func runSSERetryClient(ctx context.Context, serverURL string) error {
// TODO: this scenario is not passing yet. It requires a fix in the client SSE handling.
func runSSERetryClient(ctx context.Context, serverURL string, _ map[string]any) error {
session, err := connectToServer(ctx, serverURL)
if err != nil {
return err
@ -185,6 +186,7 @@ func main() {
serverURL := os.Args[1]
scenarioName := os.Getenv("MCP_CONFORMANCE_SCENARIO")
configCtx := getConformanceContext()
if scenarioName == "" {
printUsageAndExit("MCP_CONFORMANCE_SCENARIO not set")
@ -196,11 +198,21 @@ func main() {
}
ctx := context.Background()
if err := handler(ctx, serverURL); err != nil {
if err := handler(ctx, serverURL, configCtx); err != nil {
log.Fatalf("Scenario %q failed: %v", scenarioName, err)
}
}
func getConformanceContext() map[string]any {
ctxStr := os.Getenv("MCP_CONFORMANCE_CONTEXT")
if ctxStr == "" {
return nil
}
var ctx map[string]any
_ = json.Unmarshal([]byte(ctxStr), &ctx)
return ctx
}
func printUsageAndExit(format string, args ...any) {
var scenarios []string
for name := range registry {
@ -214,6 +226,7 @@ func printUsageAndExit(format string, args ...any) {
type connectConfig struct {
clientOptions *mcp.ClientOptions
oauthHandler auth.OAuthHandler
}
type connectOption func(*connectConfig)
@ -237,11 +250,14 @@ func connectToServer(ctx context.Context, serverURL string, opts ...connectOptio
Version: "1.0.0",
}, config.clientOptions)
transport := &mcp.StreamableClientTransport{Endpoint: serverURL}
transport := &mcp.StreamableClientTransport{
Endpoint: serverURL,
OAuthHandler: config.oauthHandler,
}
session, err := client.Connect(ctx, transport, nil)
if err != nil {
return nil, fmt.Errorf("client.Connect(): %v", err)
return nil, fmt.Errorf("client.Connect(): %w", err)
}
return session, nil

61
docs/protocol.md
View file

@ -306,9 +306,55 @@ The [_auth middleware example_](https://github.com/modelcontextprotocol/go-sdk/
### Client
Client-side OAuth is implemented by setting
[`StreamableClientTransport.HTTPClient`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk@v0.5.0/mcp#StreamableClientTransport.HTTPClient) to a custom [`http.Client`](https://pkg.go.dev/net/http#Client)
Additional support is forthcoming; see modelcontextprotocol/go-sdk#493.
> [!IMPORTANT]
> Client-side OAuth support is currently experimental and requires the `mcp_go_client_oauth` build tag to compile.
> API changes may still be made, based on developer feedback. The build tag will be removed in `v1.5.0`, which
> is planned to be released by the end of March 2026.
Client-side authorization is supported via the
[`StreamableClientTransport.OAuthHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#StreamableClientTransport.OAuthHandler)
field. If the handler is provided, the transport will automatically use it to
add an `Authorization: Bearer <token>` header to every request. The transport
will also call the handler's `Authorize` method if the server returns
`401 Unauthorized` or `403 Forbidden` errors to perform the authorization flow
or facilitate scope step-up authorization.
The SDK implements the Authorization Code flow in
[`auth.AuthorizationCodeHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#AuthorizationCodeHandler).
This handler supports:
- [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents)
- [Pre-registered clients](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#preregistration)
- [Dynamic Client Registration](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration)
To use it, configure the handler and assign it to the transport:
```go
authHandler, _ := auth.NewAuthorizationCodeHandler(&auth.AuthorizationCodeHandlerConfig{
RedirectURL: "https://myapp.com/oauth2-callback",
// Configure one of the following:
// ClientIDMetadataDocumentConfig: ...
// PreregisteredClientConfig: ...
// DynamicClientRegistrationConfig: ...
AuthorizationCodeFetcher: func(ctx context.Context, args *auth.AuthorizationArgs) (*auth.AuthorizationResult, error) {
// Open the args.URL in a browser and return the resulting code and state.
// See full example in examples/auth/client/main.go.
code := ...
state := ...
return &auth.AuthorizationResult{Code: code, State: state}, nil
},
})
transport := &mcp.StreamableClientTransport{
Endpoint: "https://example.com/mcp",
OAuthHandler: authHandler,
}
client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, nil)
session, err := client.Connect(ctx, transport, nil)
```
The `auth.AuthorizationCodeHandler` automatically manages token refreshing
and step-up authentication (when the server returns `insufficient_scope` error).
## Security
@ -317,9 +363,12 @@ the MCP spec's [Security Best Practices](https://modelcontextprotocol.io/specifi
### Confused Deputy
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation), obtaining user consent for dynamically registered clients,
happens on the MCP client. At present we don't provide client-side OAuth support.
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation),
obtaining user consent for dynamically registered clients, is mostly the
responsibility of the MCP Proxy server implementation. The SDK client does
generate cryptographically secure random `state` values for each authorization
request by default and validates them when the authorization code is returned.
Mismatched state values will result in an error.
### Token Passthrough

130
examples/auth/client/main.go Normal file
View file

@ -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)
}
}

167
examples/auth/server/main.go Normal file
View file

@ -0,0 +1,167 @@
// 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.
package main
import (
"context"
"encoding/json"
"flag"
"fmt"
"log"
"net/http"
"net/http/httputil"
"net/url"
"strings"
"time"
"github.com/modelcontextprotocol/go-sdk/auth"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/modelcontextprotocol/go-sdk/oauthex"
)
// Flags.
var (
port = flag.Int("port", 8000, "Port to listen on")
)
// Configuration required for this example.
var (
// Authorization server to return in the protected resource metadata.
authorizationServer = ""
// Introspection endpoint for verifying tokens.
introspectionEndpoint = ""
// Client credentials used in the introspection request.
clientID = ""
clientSecret = ""
)
func verifyToken(ctx context.Context, token string, _ *http.Request) (*auth.TokenInfo, error) {
data := url.Values{}
data.Set("token", token)
data.Set("token_type_hint", "access_token")
req, err := http.NewRequestWithContext(ctx, "POST", introspectionEndpoint, strings.NewReader(data.Encode()))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.Header.Set("Accept", "application/json")
req.SetBasicAuth(clientID, clientSecret)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
dump, _ := httputil.DumpResponse(resp, true)
log.Printf("Introspection failed: %s", dump)
return nil, fmt.Errorf("introspection failed with status %d", resp.StatusCode)
}
var result struct {
Active bool `json:"active"`
Scope string `json:"scope"`
Exp int64 `json:"exp"`
Sub string `json:"sub"`
}
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return nil, err
}
if !result.Active {
return nil, auth.ErrInvalidToken
}
return &auth.TokenInfo{
Scopes: strings.Fields(result.Scope),
Expiration: time.Unix(result.Exp, 0),
UserID: result.Sub,
}, nil
}
type args struct {
Input string `json:"input"`
}
func echo(ctx context.Context, req *mcp.CallToolRequest, args args) (*mcp.CallToolResult, any, error) {
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: args.Input},
},
}, nil, nil
}
func main() {
flag.Parse()
metadata := &oauthex.ProtectedResourceMetadata{
Resource: fmt.Sprintf("http://localhost:%d/mcp", *port),
AuthorizationServers: []string{authorizationServer},
ScopesSupported: []string{"read"},
}
http.Handle("/.well-known/oauth-protected-resource", auth.ProtectedResourceMetadataHandler(metadata))
server := mcp.NewServer(&mcp.Implementation{
Name: "test-server",
Version: "1.0.0",
}, nil)
server.AddReceivingMiddleware(createLoggingMiddleware())
mcp.AddTool(server, &mcp.Tool{Name: "echo"}, echo)
handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
return server
}, nil)
authMiddleware := auth.RequireBearerToken(verifyToken, &auth.RequireBearerTokenOptions{
Scopes: []string{"read"},
ResourceMetadataURL: fmt.Sprintf("http://localhost:%d/.well-known/oauth-protected-resource", *port),
})
http.Handle("/mcp", authMiddleware(handler))
log.Printf("Starting server on http://localhost:%d", *port)
log.Fatal(http.ListenAndServe(fmt.Sprintf("localhost:%d", *port), nil))
}
// createLoggingMiddleware creates an MCP middleware that logs method calls.
func createLoggingMiddleware() mcp.Middleware {
return func(next mcp.MethodHandler) mcp.MethodHandler {
return func(
ctx context.Context,
method string,
req mcp.Request,
) (mcp.Result, error) {
start := time.Now()
sessionID := req.GetSession().ID()
// Log request details.
log.Printf("[REQUEST] Session: %s | Method: %s",
sessionID,
method)
// Call the actual handler.
result, err := next(ctx, method, req)
// Log response details.
duration := time.Since(start)
if err != nil {
log.Printf("[RESPONSE] Session: %s | Method: %s | Status: ERROR | Duration: %v | Error: %v",
sessionID,
method,
duration,
err)
} else {
log.Printf("[RESPONSE] Session: %s | Method: %s | Status: OK | Duration: %v",
sessionID,
method,
duration)
}
return result, err
}
}
}

61
internal/docs/protocol.src.md
View file

@ -232,9 +232,55 @@ The [_auth middleware example_](https://github.com/modelcontextprotocol/go-sdk/
### Client
Client-side OAuth is implemented by setting
[`StreamableClientTransport.HTTPClient`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk@v0.5.0/mcp#StreamableClientTransport.HTTPClient) to a custom [`http.Client`](https://pkg.go.dev/net/http#Client)
Additional support is forthcoming; see modelcontextprotocol/go-sdk#493.
> [!IMPORTANT]
> Client-side OAuth support is currently experimental and requires the `mcp_go_client_oauth` build tag to compile.
> API changes may still be made, based on developer feedback. The build tag will be removed in `v1.5.0`, which
> is planned to be released by the end of March 2026.
Client-side authorization is supported via the
[`StreamableClientTransport.OAuthHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#StreamableClientTransport.OAuthHandler)
field. If the handler is provided, the transport will automatically use it to
add an `Authorization: Bearer <token>` header to every request. The transport
will also call the handler's `Authorize` method if the server returns
`401 Unauthorized` or `403 Forbidden` errors to perform the authorization flow
or facilitate scope step-up authorization.
The SDK implements the Authorization Code flow in
[`auth.AuthorizationCodeHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#AuthorizationCodeHandler).
This handler supports:
- [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents)
- [Pre-registered clients](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#preregistration)
- [Dynamic Client Registration](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration)
To use it, configure the handler and assign it to the transport:
```go
authHandler, _ := auth.NewAuthorizationCodeHandler(&auth.AuthorizationCodeHandlerConfig{
RedirectURL: "https://myapp.com/oauth2-callback",
// Configure one of the following:
// ClientIDMetadataDocumentConfig: ...
// PreregisteredClientConfig: ...
// DynamicClientRegistrationConfig: ...
AuthorizationCodeFetcher: func(ctx context.Context, args *auth.AuthorizationArgs) (*auth.AuthorizationResult, error) {
// Open the args.URL in a browser and return the resulting code and state.
// See full example in examples/auth/client/main.go.
code := ...
state := ...
return &auth.AuthorizationResult{Code: code, State: state}, nil
},
})
transport := &mcp.StreamableClientTransport{
Endpoint: "https://example.com/mcp",
OAuthHandler: authHandler,
}
client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, nil)
session, err := client.Connect(ctx, transport, nil)
```
The `auth.AuthorizationCodeHandler` automatically manages token refreshing
and step-up authentication (when the server returns `insufficient_scope` error).
## Security
@ -243,9 +289,12 @@ the MCP spec's [Security Best Practices](https://modelcontextprotocol.io/specifi
### Confused Deputy
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation), obtaining user consent for dynamically registered clients,
happens on the MCP client. At present we don't provide client-side OAuth support.
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation),
obtaining user consent for dynamically registered clients, is mostly the
responsibility of the MCP Proxy server implementation. The SDK client does
generate cryptographically secure random `state` values for each authorization
request by default and validates them when the authorization code is returned.
Mismatched state values will result in an error.
### Token Passthrough

304
internal/oauthtest/fake_authorization_server.go Normal file
View file

@ -0,0 +1,304 @@
// 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 oauthtest
import (
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"io"
"maps"
"net/http"
"net/http/httptest"
"slices"
"testing"
internaljson "github.com/modelcontextprotocol/go-sdk/internal/json"
"github.com/modelcontextprotocol/go-sdk/oauthex"
)
type ClientInfo struct {
Secret string
RedirectURIs []string
}
type MetadataEndpointConfig struct {
// Whether to serve the OAuth Authorization Server Metadata at
// /.well-known/oauth-authorization-server + issuerPath.
ServeOAuthInsertedEndpoint bool
// Whether to serve the OAuth Authorization Server Metadata at
// /.well-known/openid-configuration + issuerPath.
ServeOpenIDInsertedEndpoint bool
// Whether to serve the OAuth Authorization Server Metadata at
// issuerPath + /.well-known/openid-configuration.
// Should be used when issuerPath is not empty.
ServeOpenIDAppendedEndpoint bool
}
type RegistrationConfig struct {
// Whether the client ID metadata document is supported.
ClientIDMetadataDocumentSupported bool
// PreregisteredClients is a map of valid ClientIDs to ClientSecrets.
PreregisteredClients map[string]ClientInfo
// Whether dynamic client registration is enabled.
DynamicClientRegistrationEnabled bool
}
// Config holds configuration for FakeAuthorizationServer.
type Config struct {
// The optional path component of the issuer URL.
// If non-empty, it should start with a "/". It should not end with a "/".
// It affects the paths of the server endpoints.
IssuerPath string
// Configuration of the metadata endpoint.
MetadataEndpointConfig *MetadataEndpointConfig
// Configuration for client registration.
RegistrationConfig *RegistrationConfig
}
// FakeAuthorizationServer is a fake OAuth 2.0 Authorization Server for testing.
type FakeAuthorizationServer struct {
server *httptest.Server
Mux *http.ServeMux
config Config
clients map[string]ClientInfo
codes map[string]codeInfo
}
type codeInfo struct {
CodeChallenge string
}
// NewFakeAuthorizationServer creates a new FakeAuthorizationServer.
// The server is simple and should not be used outside of testing.
// It supports:
// - Only the authorization Code Grant
// - PKCE verification
// - Client tracking & dynamic registration
// - Client authentication
func NewFakeAuthorizationServer(config Config) *FakeAuthorizationServer {
s := &FakeAuthorizationServer{
Mux: http.NewServeMux(),
config: config,
codes: make(map[string]codeInfo),
}
if config.RegistrationConfig != nil {
s.clients = maps.Clone(config.RegistrationConfig.PreregisteredClients)
}
if s.clients == nil {
s.clients = make(map[string]ClientInfo)
}
s.Mux.HandleFunc(s.config.IssuerPath+"/authorize", s.handleAuthorize)
s.Mux.HandleFunc(s.config.IssuerPath+"/token", s.handleToken)
if config.MetadataEndpointConfig != nil {
if config.MetadataEndpointConfig.ServeOAuthInsertedEndpoint {
s.Mux.HandleFunc("/.well-known/oauth-authorization-server"+s.config.IssuerPath, s.handleMetadata)
}
if config.MetadataEndpointConfig.ServeOpenIDInsertedEndpoint {
s.Mux.HandleFunc("/.well-known/openid-configuration"+s.config.IssuerPath, s.handleMetadata)
}
if config.MetadataEndpointConfig.ServeOpenIDAppendedEndpoint && s.config.IssuerPath != "" {
s.Mux.HandleFunc(s.config.IssuerPath+"/.well-known/openid-configuration", s.handleMetadata)
}
} else {
// Serve the default OAuth endpoint.
s.Mux.HandleFunc("/.well-known/oauth-authorization-server", s.handleMetadata)
}
if config.RegistrationConfig != nil && config.RegistrationConfig.DynamicClientRegistrationEnabled {
s.Mux.HandleFunc(s.config.IssuerPath+"/register", s.handleRegister)
}
s.server = httptest.NewUnstartedServer(s.Mux)
return s
}
// Start starts the HTTP server and registers a cleanup function on t to close the server.
func (s *FakeAuthorizationServer) Start(t testing.TB) {
s.server.Start()
t.Cleanup(s.server.Close)
}
// URL returns the base URL of the server (Issuer).
func (s *FakeAuthorizationServer) URL() string {
return s.server.URL
}
func (s *FakeAuthorizationServer) handleMetadata(w http.ResponseWriter, r *http.Request) {
cimdSupported := false
var registrationEndpoint string
if s.config.RegistrationConfig != nil {
cimdSupported = s.config.RegistrationConfig.ClientIDMetadataDocumentSupported
if s.config.RegistrationConfig.DynamicClientRegistrationEnabled {
registrationEndpoint = s.URL() + s.config.IssuerPath + "/register"
}
}
meta := &oauthex.AuthServerMeta{
Issuer: s.URL() + s.config.IssuerPath,
AuthorizationEndpoint: s.URL() + s.config.IssuerPath + "/authorize",
TokenEndpoint: s.URL() + s.config.IssuerPath + "/token",
RegistrationEndpoint: registrationEndpoint,
ResponseTypesSupported: []string{"code"},
CodeChallengeMethodsSupported: []string{"S256"},
ClientIDMetadataDocumentSupported: cimdSupported,
TokenEndpointAuthMethodsSupported: []string{"client_secret_post", "client_secret_basic"},
}
// Set CORS headers for cross-origin client discovery.
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
// Handle CORS preflight requests
if r.Method == http.MethodOptions {
w.WriteHeader(http.StatusNoContent)
return
}
// Only GET allowed for metadata retrieval
if r.Method != http.MethodGet {
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
w.Header().Set("Content-Type", "application/json")
if err := json.NewEncoder(w).Encode(meta); err != nil {
http.Error(w, "Failed to encode metadata", http.StatusInternalServerError)
return
}
}
func (s *FakeAuthorizationServer) handleRegister(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
var metadata oauthex.ClientRegistrationMetadata
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "failed to read request body", http.StatusBadRequest)
return
}
if err := internaljson.Unmarshal(body, &metadata); err != nil {
http.Error(w, "failed to parse request", http.StatusBadRequest)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
clientID := rand.Text()
ci := ClientInfo{
Secret: rand.Text(),
RedirectURIs: metadata.RedirectURIs,
}
s.clients[clientID] = ci
metadata.TokenEndpointAuthMethod = "client_secret_basic"
json.NewEncoder(w).Encode(&oauthex.ClientRegistrationResponse{
ClientID: clientID,
ClientSecret: ci.Secret,
ClientRegistrationMetadata: metadata,
})
}
func (s *FakeAuthorizationServer) handleAuthorize(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
clientID := r.URL.Query().Get("client_id")
clientInfo, ok := s.clients[clientID]
if !ok {
http.Error(w, "unknown client_id", http.StatusBadRequest)
return
}
redirectURI := r.URL.Query().Get("redirect_uri")
if redirectURI == "" {
http.Error(w, "missing redirect_uri", http.StatusBadRequest)
return
}
if !slices.Contains(clientInfo.RedirectURIs, redirectURI) {
http.Error(w, "invalid redirect_uri", http.StatusBadRequest)
return
}
codeChallenge := r.URL.Query().Get("code_challenge")
if codeChallenge == "" {
http.Error(w, "missing code_challenge", http.StatusBadRequest)
return
}
code := rand.Text()
s.codes[code] = codeInfo{
CodeChallenge: codeChallenge,
}
state := r.URL.Query().Get("state")
redirectURL := fmt.Sprintf("%s?code=%s&state=%s", redirectURI, code, state)
http.Redirect(w, r, redirectURL, http.StatusFound)
}
func (s *FakeAuthorizationServer) handleToken(w http.ResponseWriter, r *http.Request) {
if err := r.ParseForm(); err != nil {
http.Error(w, "failed to parse form", http.StatusBadRequest)
return
}
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
if err := s.authenticateClient(r); err != nil {
http.Error(w, err.Error(), http.StatusUnauthorized)
return
}
if r.Form.Get("grant_type") != "authorization_code" {
http.Error(w, "invalid grant_type", http.StatusBadRequest)
return
}
code := r.Form.Get("code")
if code == "" {
http.Error(w, "missing code", http.StatusBadRequest)
return
}
codeInfo, ok := s.codes[code]
if !ok {
http.Error(w, "unknown authorization code", http.StatusBadRequest)
return
}
verifier := r.Form.Get("code_verifier")
if verifier == "" {
http.Error(w, "missing code_verifier", http.StatusBadRequest)
return
}
sha := sha256.Sum256([]byte(verifier))
expectedChallenge := base64.RawURLEncoding.EncodeToString(sha[:])
if expectedChallenge != codeInfo.CodeChallenge {
http.Error(w, "PKCE verification failed", http.StatusBadRequest)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{
"access_token": "test_access_token",
"token_type": "Bearer",
"expires_in": 3600,
})
}
func (s *FakeAuthorizationServer) authenticateClient(r *http.Request) error {
clientID, clientSecret, ok := r.BasicAuth()
if !ok {
clientID = r.Form.Get("client_id")
clientSecret = r.Form.Get("client_secret")
}
clientInfo, ok := s.clients[clientID]
if !ok || clientInfo.Secret != clientSecret {
return errors.New("client not found")
}
return nil
}

13
internal/readme/README.src.md
View file

@ -33,10 +33,15 @@ contains feature documentation, mapping the MCP spec to the packages above.
The following table shows which versions of the Go SDK support which versions of the MCP specification:
| SDK Version | Latest MCP Spec | All Supported MCP Specs |
|-----------------|-------------------|------------------------------------------------|
| v1.2.0+ | 2025-06-18 | 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 |
| v1.0.0 - v1.1.0 | 2025-06-18 | 2025-06-18, 2025-03-26, 2024-11-05 |
| SDK Version | Latest MCP Spec | All Supported MCP Specs |
|-----------------|-------------------|----------------------------------------------------|
| v1.4.0+ | 2025-11-25\* | 2025-11-25\*, 2025-06-18, 2025-03-26, 2024-11-05 |
| v1.2.0 - v1.3.1 | 2025-11-25\*\* | 2025-11-25\*\*, 2025-06-18, 2025-03-26, 2024-11-05 |
| v1.0.0 - v1.1.0 | 2025-06-18 | 2025-06-18, 2025-03-26, 2024-11-05 |
\* Client side OAuth has experimental support.
\*\* Partial support for 2025-11-25 (client side OAuth and Sampling with tools not available).
New releases of the SDK target only supported versions of Go. See
https://go.dev/doc/devel/release#policy for more information.

88
mcp/streamable.go
View file

@ -26,7 +26,6 @@ import (
"strconv"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/modelcontextprotocol/go-sdk/auth"
@ -1456,6 +1455,9 @@ type StreamableClientTransport struct {
// - You want to avoid maintaining a persistent connection
DisableStandaloneSSE bool
// OAuthHandler is an optional field that, if provided, will be used to authorize the requests.
OAuthHandler auth.OAuthHandler
// TODO(rfindley): propose exporting these.
// If strict is set, the transport is in 'strict mode', where any violation
// of the MCP spec causes a failure.
@ -1531,6 +1533,7 @@ func (t *StreamableClientTransport) Connect(ctx context.Context) (Connection, er
cancel: cancel,
failed: make(chan struct{}),
disableStandaloneSSE: t.DisableStandaloneSSE,
oauthHandler: t.OAuthHandler,
}
return conn, nil
}
@ -1549,6 +1552,9 @@ type streamableClientConn struct {
// for receiving server-to-client notifications when no request is in flight.
disableStandaloneSSE bool // from [StreamableClientTransport.DisableStandaloneSSE]
// oauthHandler is the OAuth handler for the connection.
oauthHandler auth.OAuthHandler // from [StreamableClientTransport.OAuthHandler]
// Guard calls to Close, as it may be called multiple times.
closeOnce sync.Once
closeErr error
@ -1718,20 +1724,46 @@ func (c *streamableClientConn) Write(ctx context.Context, msg jsonrpc.Message) e
return fmt.Errorf("%s: %v", requestSummary, err)
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url, bytes.NewReader(data))
doRequest := func() (*http.Request, *http.Response, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url, bytes.NewReader(data))
if err != nil {
return nil, nil, err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json, text/event-stream")
if err := c.setMCPHeaders(req); err != nil {
// Failure to set headers means that the request was not sent.
// Wrap with ErrRejected so the jsonrpc2 connection doesn't set writeErr
// and permanently break the connection.
return nil, nil, fmt.Errorf("%s: %w: %v", requestSummary, jsonrpc2.ErrRejected, err)
}
resp, err := c.client.Do(req)
if err != nil {
// Any error from client.Do means the request didn't reach the server.
// Wrap with ErrRejected so the jsonrpc2 connection doesn't set writeErr
// and permanently break the connection.
err = fmt.Errorf("%s: %w: %v", requestSummary, jsonrpc2.ErrRejected, err)
}
return req, resp, err
}
req, resp, err := doRequest()
if err != nil {
return err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json, text/event-stream")
c.setMCPHeaders(req)
resp, err := c.client.Do(req)
if err != nil {
// Any error from client.Do means the request didn't reach the server.
// Wrap with ErrRejected so the jsonrpc2 connection doesn't set writeErr
// and permanently break the connection.
return fmt.Errorf("%w: %s: %v", jsonrpc2.ErrRejected, requestSummary, err)
if (resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden) && c.oauthHandler != nil {
if err := c.oauthHandler.Authorize(ctx, req, resp); err != nil {
// Wrap with ErrRejected so the jsonrpc2 connection doesn't set writeErr
// and permanently break the connection.
// Wrap the authorization error as well for client inspection.
return fmt.Errorf("%s: %w: %w", requestSummary, jsonrpc2.ErrRejected, err)
}
// Retry the request after successful authorization.
_, resp, err = doRequest()
if err != nil {
return err
}
}
if err := c.checkResponse(requestSummary, resp); err != nil {
@ -1799,23 +1831,32 @@ func (c *streamableClientConn) Write(ctx context.Context, msg jsonrpc.Message) e
return nil
}
// testAuth controls whether a fake Authorization header is added to outgoing requests.
// TODO: replace with a better mechanism when client-side auth is in place.
var testAuth atomic.Bool
func (c *streamableClientConn) setMCPHeaders(req *http.Request) {
func (c *streamableClientConn) setMCPHeaders(req *http.Request) error {
c.mu.Lock()
defer c.mu.Unlock()
if c.oauthHandler != nil {
ts, err := c.oauthHandler.TokenSource(c.ctx)
if err != nil {
return err
}
if ts != nil {
token, err := ts.Token()
if err != nil {
return err
}
if token != nil {
req.Header.Set("Authorization", "Bearer "+token.AccessToken)
}
}
}
if c.initializedResult != nil {
req.Header.Set(protocolVersionHeader, c.initializedResult.ProtocolVersion)
}
if c.sessionID != "" {
req.Header.Set(sessionIDHeader, c.sessionID)
}
if testAuth.Load() {
req.Header.Set("Authorization", "Bearer foo")
}
return nil
}
func (c *streamableClientConn) handleJSON(requestSummary string, resp *http.Response) {
@ -2068,7 +2109,9 @@ func (c *streamableClientConn) connectSSE(ctx context.Context, lastEventID strin
if err != nil {
return nil, err
}
c.setMCPHeaders(req)
if err := c.setMCPHeaders(req); err != nil {
return nil, err
}
if lastEventID != "" {
req.Header.Set(lastEventIDHeader, lastEventID)
}
@ -2099,8 +2142,9 @@ func (c *streamableClientConn) Close() error {
if err != nil {
c.closeErr = err
} else {
c.setMCPHeaders(req)
if _, err := c.client.Do(req); err != nil {
if err := c.setMCPHeaders(req); err != nil {
c.closeErr = err
} else if _, err := c.client.Do(req); err != nil {
c.closeErr = err
}
}

179
mcp/streamable_client_auth_test.go Normal file
View file

@ -0,0 +1,179 @@
// Copyright 2026 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package mcp
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"github.com/modelcontextprotocol/go-sdk/auth"
"golang.org/x/oauth2"
)
type mockOAuthHandler struct {
// Embed to satisfy the interface.
auth.AuthorizationCodeHandler
token *oauth2.Token
authorizeErr error
authorizeCalled bool
}
func (h *mockOAuthHandler) TokenSource(ctx context.Context) (oauth2.TokenSource, error) {
if h.token == nil {
return nil, nil
}
return oauth2.StaticTokenSource(h.token), nil
}
func (h *mockOAuthHandler) Authorize(ctx context.Context, req *http.Request, resp *http.Response) error {
h.authorizeCalled = true
return h.authorizeErr
}
func TestStreamableClientOAuth_AuthorizationHeader(t *testing.T) {
ctx := context.Background()
token := &oauth2.Token{AccessToken: "test-token"}
oauthHandler := &mockOAuthHandler{token: token}
fake := &fakeStreamableServer{
t: t,
responses: fakeResponses{
{"POST", "", methodInitialize, ""}: {
header: header{
"Content-Type": "application/json",
sessionIDHeader: "123",
},
body: jsonBody(t, initResp),
},
{"POST", "123", notificationInitialized, ""}: {
status: http.StatusAccepted,
wantProtocolVersion: latestProtocolVersion,
},
{"GET", "123", "", ""}: {
header: header{
"Content-Type": "text/event-stream",
},
},
{"DELETE", "123", "", ""}: {},
},
}
verifier := func(ctx context.Context, token string, req *http.Request) (*auth.TokenInfo, error) {
if token != "test-token" {
return nil, auth.ErrInvalidToken
}
return &auth.TokenInfo{Expiration: time.Now().Add(time.Hour)}, nil
}
httpServer := httptest.NewServer(auth.RequireBearerToken(verifier, nil)(fake))
t.Cleanup(httpServer.Close)
transport := &StreamableClientTransport{
Endpoint: httpServer.URL,
OAuthHandler: oauthHandler,
}
client := NewClient(testImpl, nil)
session, err := client.Connect(ctx, transport, nil)
if err != nil {
t.Fatalf("client.Connect() failed: %v", err)
}
session.Close()
}
func TestStreamableClientOAuth_401(t *testing.T) {
ctx := context.Background()
oauthHandler := &mockOAuthHandler{token: nil}
fake := &fakeStreamableServer{
t: t,
responses: fakeResponses{
{"POST", "", methodInitialize, ""}: {
header: header{
"Content-Type": "application/json",
sessionIDHeader: "123",
},
body: jsonBody(t, initResp),
},
},
}
verifier := func(ctx context.Context, token string, req *http.Request) (*auth.TokenInfo, error) {
// Accept any token.
return &auth.TokenInfo{Expiration: time.Now().Add(time.Hour)}, nil
}
httpServer := httptest.NewServer(auth.RequireBearerToken(verifier, nil)(fake))
t.Cleanup(httpServer.Close)
transport := &StreamableClientTransport{
Endpoint: httpServer.URL,
OAuthHandler: oauthHandler,
}
client := NewClient(testImpl, nil)
_, err := client.Connect(ctx, transport, nil)
if err == nil || !strings.Contains(err.Error(), "Unauthorized") {
t.Fatalf("client.Connect() error does not contain 'Unauthorized': %v", err)
}
if !oauthHandler.authorizeCalled {
t.Errorf("expected Authorize to be called")
}
}
func TestTokenInfo(t *testing.T) {
ctx := context.Background()
// Create a server with a tool that returns TokenInfo.
tokenInfo := func(ctx context.Context, req *CallToolRequest, _ struct{}) (*CallToolResult, any, error) {
return &CallToolResult{Content: []Content{&TextContent{Text: fmt.Sprintf("%v", req.Extra.TokenInfo)}}}, nil, nil
}
server := NewServer(testImpl, nil)
AddTool(server, &Tool{Name: "tokenInfo", Description: "return token info"}, tokenInfo)
streamHandler := NewStreamableHTTPHandler(func(req *http.Request) *Server { return server }, nil)
verifier := func(ctx context.Context, token string, req *http.Request) (*auth.TokenInfo, error) {
if token != "test-token" {
return nil, auth.ErrInvalidToken
}
return &auth.TokenInfo{
Scopes: []string{"scope"},
// Expiration is far, far in the future.
Expiration: time.Date(5000, 1, 2, 3, 4, 5, 0, time.UTC),
}, nil
}
handler := auth.RequireBearerToken(verifier, nil)(streamHandler)
httpServer := httptest.NewServer(mustNotPanic(t, handler))
defer httpServer.Close()
transport := &StreamableClientTransport{
Endpoint: httpServer.URL,
OAuthHandler: &mockOAuthHandler{token: &oauth2.Token{AccessToken: "test-token"}},
}
client := NewClient(testImpl, nil)
session, err := client.Connect(ctx, transport, nil)
if err != nil {
t.Fatalf("client.Connect() failed: %v", err)
}
defer session.Close()
res, err := session.CallTool(ctx, &CallToolParams{Name: "tokenInfo"})
if err != nil {
t.Fatal(err)
}
if len(res.Content) == 0 {
t.Fatal("missing content")
}
tc, ok := res.Content[0].(*TextContent)
if !ok {
t.Fatal("not TextContent")
}
if g, w := tc.Text, "&{[scope] 5000-01-02 03:04:05 +0000 UTC map[]}"; g != w {
t.Errorf("got %q, want %q", g, w)
}
}

1
mcp/streamable_client_test.go
View file

@ -17,7 +17,6 @@ import (
"time"
"github.com/google/go-cmp/cmp"
"github.com/modelcontextprotocol/go-sdk/internal/jsonrpc2"
"github.com/modelcontextprotocol/go-sdk/jsonrpc"
)

49
mcp/streamable_test.go
View file

@ -1666,55 +1666,6 @@ func textContent(t *testing.T, res *CallToolResult) string {
return text.Text
}
func TestTokenInfo(t *testing.T) {
oldAuth := testAuth.Load()
defer testAuth.Store(oldAuth)
testAuth.Store(true)
ctx := context.Background()
// Create a server with a tool that returns TokenInfo.
tokenInfo := func(ctx context.Context, req *CallToolRequest, _ struct{}) (*CallToolResult, any, error) {
return &CallToolResult{Content: []Content{&TextContent{Text: fmt.Sprintf("%v", req.Extra.TokenInfo)}}}, nil, nil
}
server := NewServer(testImpl, nil)
AddTool(server, &Tool{Name: "tokenInfo", Description: "return token info"}, tokenInfo)
streamHandler := NewStreamableHTTPHandler(func(req *http.Request) *Server { return server }, nil)
verifier := func(context.Context, string, *http.Request) (*auth.TokenInfo, error) {
return &auth.TokenInfo{
Scopes: []string{"scope"},
// Expiration is far, far in the future.
Expiration: time.Date(5000, 1, 2, 3, 4, 5, 0, time.UTC),
}, nil
}
handler := auth.RequireBearerToken(verifier, nil)(streamHandler)
httpServer := httptest.NewServer(mustNotPanic(t, handler))
defer httpServer.Close()
transport := &StreamableClientTransport{Endpoint: httpServer.URL}
client := NewClient(testImpl, nil)
session, err := client.Connect(ctx, transport, nil)
if err != nil {
t.Fatalf("client.Connect() failed: %v", err)
}
defer session.Close()
res, err := session.CallTool(ctx, &CallToolParams{Name: "tokenInfo"})
if err != nil {
t.Fatal(err)
}
if len(res.Content) == 0 {
t.Fatal("missing content")
}
tc, ok := res.Content[0].(*TextContent)
if !ok {
t.Fatal("not TextContent")
}
if g, w := tc.Text, "&{[scope] 5000-01-02 03:04:05 +0000 UTC map[]}"; g != w {
t.Errorf("got %q, want %q", g, w)
}
}
func TestSessionHijackingPrevention(t *testing.T) {
// This test verifies that sessions bound to a user ID cannot be accessed
// by a different user (session hijacking prevention).

Some files were not shown because too many files have changed in this diff Show more