Scope challenge http (#1925)

* initial oauth metadata implementation

* add nolint for GetEffectiveHostAndScheme

* remove CAPI reference

* remove nonsensical example URL

* anonymize

* add oauth tests

* replace custom protected resource metadata handler with our own

* remove unused header

* Update pkg/http/oauth/oauth.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* pass oauth config to mcp handler for token extraction

* chore: retrigger ci

* align types with base branch

* update more types

* initial oauth metadata implementation

* add nolint for GetEffectiveHostAndScheme

* remove CAPI reference

* remove nonsensical example URL

* anonymize

* add oauth tests

* replace custom protected resource metadata handler with our own

* Update pkg/http/oauth/oauth.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: retrigger ci

* update more types

* remove CAPI specific header

* restore mcp path specific logic

* WIP

* implement better resource path handling for OAuth server

* return auth handler to lib version

* rename to base-path flag

* Add scopes challenge middleware to HTTP handler and initialize global tool scope map

* Flags on the http command

* Add tests for scope maps

* Add scope challenge & pat filtering based on token scopes

* Add scope filtering if challenge is enabled

* Linter fixes and renamed scope challenge to PAT scope filter

* Linter issues.

* Remove unsused methoodod FetchScopesFromGitHubAPI, store active scopes in context

* Require an API host when creating scope fetchers

* Add tests for MCP parsing middleware

* Remove IDE token support, these will never work. Add tests.

* Move ForMCPRequest call to HTTP handler & explicitly set capabilities

---------

Co-authored-by: Matt Holloway <mattdholloway@pm.me>
Co-authored-by: Matt Holloway <mattdholloway@github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

cmd/github-mcp-server/main.go

@@ -109,6 +109,7 @@ var (
 				ContentWindowSize:    viper.GetInt("content-window-size"),
 				LockdownMode:         viper.GetBool("lockdown-mode"),
 				RepoAccessCacheTTL:   &ttl,
+				ScopeChallenge:       viper.GetBool("scope-challenge"),
 			}
 
 			return ghhttp.RunHTTPServer(httpConfig)
@@ -141,6 +142,7 @@ func init() {
 	httpCmd.Flags().Int("port", 8082, "HTTP server port")
 	httpCmd.Flags().String("base-url", "", "Base URL where this server is publicly accessible (for OAuth resource metadata)")
 	httpCmd.Flags().String("base-path", "", "Externally visible base path for the HTTP server (for OAuth resource metadata)")
+	httpCmd.Flags().Bool("scope-challenge", false, "Enable OAuth scope challenge responses and tool filtering based on token scopes")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -159,7 +161,7 @@ func init() {
 	_ = viper.BindPFlag("port", httpCmd.Flags().Lookup("port"))
 	_ = viper.BindPFlag("base-url", httpCmd.Flags().Lookup("base-url"))
 	_ = viper.BindPFlag("base-path", httpCmd.Flags().Lookup("base-path"))
-
+	_ = viper.BindPFlag("scope-challenge", httpCmd.Flags().Lookup("scope-challenge"))
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)
 	rootCmd.AddCommand(httpCmd)

internal/ghmcp/server.go

@@ -366,14 +366,7 @@ func fetchTokenScopesForHost(ctx context.Context, token, host string) ([]string,
 		return nil, fmt.Errorf("failed to parse API host: %w", err)
 	}
 
-	baseRestURL, err := apiHost.BaseRESTURL(ctx)
-	if err != nil {
-		return nil, fmt.Errorf("failed to get base REST URL: %w", err)
-	}
-
-	fetcher := scopes.NewFetcher(scopes.FetcherOptions{
-		APIHost: baseRestURL.String(),
-	})
+	fetcher := scopes.NewFetcher(apiHost, scopes.FetcherOptions{})
 
 	return fetcher.FetchTokenScopes(ctx, token)
 }

pkg/context/mcp_info.go

@@ -0,0 +1,39 @@
+package context
+
+import "context"
+
+type mcpMethodInfoCtx string
+
+var mcpMethodInfoCtxKey mcpMethodInfoCtx = "mcpmethodinfo"
+
+// MCPMethodInfo contains pre-parsed MCP method information extracted from the JSON-RPC request.
+// This is populated early in the request lifecycle to enable:
+//   - Inventory filtering via ForMCPRequest (only register needed tools/resources/prompts)
+//   - Avoiding duplicate JSON parsing in middlewares (secret-scanning, scope-challenge)
+//   - Performance optimization for per-request server creation
+type MCPMethodInfo struct {
+	// Method is the MCP method being called (e.g., "tools/call", "tools/list", "initialize")
+	Method string
+	// ItemName is the name of the specific item being accessed (tool name, resource URI, prompt name)
+	// Only populated for call/get methods (tools/call, prompts/get, resources/read)
+	ItemName string
+	// Owner is the repository owner from tool call arguments, if present
+	Owner string
+	// Repo is the repository name from tool call arguments, if present
+	Repo string
+	// Arguments contains the raw tool arguments for tools/call requests
+	Arguments map[string]any
+}
+
+// WithMCPMethodInfo stores the MCPMethodInfo in the context.
+func WithMCPMethodInfo(ctx context.Context, info *MCPMethodInfo) context.Context {
+	return context.WithValue(ctx, mcpMethodInfoCtxKey, info)
+}
+
+// MCPMethod retrieves the MCPMethodInfo from the context.
+func MCPMethod(ctx context.Context) (*MCPMethodInfo, bool) {
+	if info, ok := ctx.Value(mcpMethodInfoCtxKey).(*MCPMethodInfo); ok {
+		return info, true
+	}
+	return nil, false
+}

pkg/context/token.go

@@ -1,19 +1,39 @@
 package context
 
-import "context"
+import (
+	"context"
+
+	"github.com/github/github-mcp-server/pkg/utils"
+)
 
 // tokenCtxKey is a context key for authentication token information
-type tokenCtxKey struct{}
+type tokenCtx string
+
+var tokenCtxKey tokenCtx = "tokenctx"
+
+type TokenInfo struct {
+	Token         string
+	TokenType     utils.TokenType
+	ScopesFetched bool
+	Scopes        []string
+}
 
 // WithTokenInfo adds TokenInfo to the context
-func WithTokenInfo(ctx context.Context, token string) context.Context {
-	return context.WithValue(ctx, tokenCtxKey{}, token)
+func WithTokenInfo(ctx context.Context, tokenInfo *TokenInfo) context.Context {
+	return context.WithValue(ctx, tokenCtxKey, tokenInfo)
+}
+
+func SetTokenScopes(ctx context.Context, scopes []string) {
+	if tokenInfo, ok := GetTokenInfo(ctx); ok {
+		tokenInfo.Scopes = scopes
+		tokenInfo.ScopesFetched = true
+	}
 }
 
 // GetTokenInfo retrieves the authentication token from the context
-func GetTokenInfo(ctx context.Context) (string, bool) {
-	if token, ok := ctx.Value(tokenCtxKey{}).(string); ok {
-		return token, true
+func GetTokenInfo(ctx context.Context) (*TokenInfo, bool) {
+	if tokenInfo, ok := ctx.Value(tokenCtxKey).(*TokenInfo); ok {
+		return tokenInfo, true
 	}
-	return "", false
+	return nil, false
 }

pkg/github/dependencies.go

@@ -282,7 +282,11 @@ func (d *RequestDeps) GetClient(ctx context.Context) (*gogithub.Client, error) {
 	}
 
 	// extract the token from the context
-	token, _ := ghcontext.GetTokenInfo(ctx)
+	tokenInfo, ok := ghcontext.GetTokenInfo(ctx)
+	if !ok {
+		return nil, fmt.Errorf("no token info in context")
+	}
+	token := tokenInfo.Token
 
 	baseRestURL, err := d.apiHosts.BaseRESTURL(ctx)
 	if err != nil {
@@ -308,7 +312,11 @@ func (d *RequestDeps) GetGQLClient(ctx context.Context) (*githubv4.Client, error
 	}
 
 	// extract the token from the context
-	token, _ := ghcontext.GetTokenInfo(ctx)
+	tokenInfo, ok := ghcontext.GetTokenInfo(ctx)
+	if !ok {
+		return nil, fmt.Errorf("no token info in context")
+	}
+	token := tokenInfo.Token
 
 	// Construct GraphQL client
 	// We use NewEnterpriseClient unconditionally since we already parsed the API host

pkg/github/server.go

@@ -73,10 +73,10 @@ type MCPServerConfig struct {
 
 type MCPServerOption func(*mcp.ServerOptions)
 
-func NewMCPServer(ctx context.Context, cfg *MCPServerConfig, deps ToolDependencies, inventory *inventory.Inventory) (*mcp.Server, error) {
+func NewMCPServer(ctx context.Context, cfg *MCPServerConfig, deps ToolDependencies, inv *inventory.Inventory) (*mcp.Server, error) {
 	// Create the MCP server
 	serverOpts := &mcp.ServerOptions{
-		Instructions:      inventory.Instructions(),
+		Instructions:      inv.Instructions(),
 		Logger:            cfg.Logger,
 		CompletionHandler: CompletionsHandler(deps.GetClient),
 	}
@@ -102,20 +102,20 @@ func NewMCPServer(ctx context.Context, cfg *MCPServerConfig, deps ToolDependenci
 	ghServer.AddReceivingMiddleware(addGitHubAPIErrorToContext)
 	ghServer.AddReceivingMiddleware(InjectDepsMiddleware(deps))
 
-	if unrecognized := inventory.UnrecognizedToolsets(); len(unrecognized) > 0 {
+	if unrecognized := inv.UnrecognizedToolsets(); len(unrecognized) > 0 {
 		cfg.Logger.Warn("Warning: unrecognized toolsets ignored", "toolsets", strings.Join(unrecognized, ", "))
 	}
 
 	// Register GitHub tools/resources/prompts from the inventory.
 	// In dynamic mode with no explicit toolsets, this is a no-op since enabledToolsets
 	// is empty - users enable toolsets at runtime via the dynamic tools below (but can
 	// enable toolsets or tools explicitly that do need registration).
-	inventory.RegisterAll(ctx, ghServer, deps)
+	inv.RegisterAll(ctx, ghServer, deps)
 
 	// Register dynamic toolset management tools (enable/disable) - these are separate
 	// meta-tools that control the inventory, not part of the inventory itself
 	if cfg.DynamicToolsets {
-		registerDynamicTools(ghServer, inventory, deps, cfg.Translator)
+		registerDynamicTools(ghServer, inv, deps, cfg.Translator)
 	}
 
 	return ghServer, nil

pkg/http/handler.go

@@ -10,7 +10,9 @@ import (
 	"github.com/github/github-mcp-server/pkg/http/middleware"
 	"github.com/github/github-mcp-server/pkg/http/oauth"
 	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/scopes"
 	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/github/github-mcp-server/pkg/utils"
 	"github.com/go-chi/chi/v5"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -23,21 +25,30 @@ type Handler struct {
 	config                 *ServerConfig
 	deps                   github.ToolDependencies
 	logger                 *slog.Logger
+	apiHosts               utils.APIHostResolver
 	t                      translations.TranslationHelperFunc
 	githubMcpServerFactory GitHubMCPServerFactoryFunc
 	inventoryFactoryFunc   InventoryFactoryFunc
 	oauthCfg               *oauth.Config
+	scopeFetcher           scopes.FetcherInterface
 }
 
 type HandlerOptions struct {
 	GitHubMcpServerFactory GitHubMCPServerFactoryFunc
 	InventoryFactory       InventoryFactoryFunc
 	OAuthConfig            *oauth.Config
+	ScopeFetcher           scopes.FetcherInterface
 	FeatureChecker         inventory.FeatureFlagChecker
 }
 
 type HandlerOption func(*HandlerOptions)
 
+func WithScopeFetcher(f scopes.FetcherInterface) HandlerOption {
+	return func(o *HandlerOptions) {
+		o.ScopeFetcher = f
+	}
+}
+
 func WithGitHubMCPServerFactory(f GitHubMCPServerFactoryFunc) HandlerOption {
 	return func(o *HandlerOptions) {
 		o.GitHubMcpServerFactory = f
@@ -68,6 +79,7 @@ func NewHTTPMcpHandler(
 	deps github.ToolDependencies,
 	t translations.TranslationHelperFunc,
 	logger *slog.Logger,
+	apiHost utils.APIHostResolver,
 	options ...HandlerOption) *Handler {
 	opts := &HandlerOptions{}
 	for _, o := range options {
@@ -79,28 +91,40 @@ func NewHTTPMcpHandler(
 		githubMcpServerFactory = DefaultGitHubMCPServerFactory
 	}
 
+	scopeFetcher := opts.ScopeFetcher
+	if scopeFetcher == nil {
+		scopeFetcher = scopes.NewFetcher(apiHost, scopes.FetcherOptions{})
+	}
+
 	inventoryFactory := opts.InventoryFactory
 	if inventoryFactory == nil {
-		inventoryFactory = DefaultInventoryFactory(cfg, t, opts.FeatureChecker)
+		inventoryFactory = DefaultInventoryFactory(cfg, t, opts.FeatureChecker, scopeFetcher)
 	}
 
 	return &Handler{
 		ctx:                    ctx,
 		config:                 cfg,
 		deps:                   deps,
 		logger:                 logger,
+		apiHosts:               apiHost,
 		t:                      t,
 		githubMcpServerFactory: githubMcpServerFactory,
 		inventoryFactoryFunc:   inventoryFactory,
 		oauthCfg:               opts.OAuthConfig,
+		scopeFetcher:           scopeFetcher,
 	}
 }
 
 func (h *Handler) RegisterMiddleware(r chi.Router) {
 	r.Use(
 		middleware.ExtractUserToken(h.oauthCfg),
 		middleware.WithRequestConfig,
+		middleware.WithMCPParse(),
 	)
+
+	if h.config.ScopeChallenge {
+		r.Use(middleware.WithScopeChallenge(h.oauthCfg, h.scopeFetcher))
+	}
 }
 
 // RegisterRoutes registers the routes for the MCP server
@@ -145,22 +169,38 @@ func withInsiders(next http.Handler) http.Handler {
 }
 
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	inventory, err := h.inventoryFactoryFunc(r)
+	inv, err := h.inventoryFactoryFunc(r)
 	if err != nil {
 		w.WriteHeader(http.StatusInternalServerError)
 		return
 	}
 
-	ghServer, err := h.githubMcpServerFactory(r, h.deps, inventory, &github.MCPServerConfig{
+	invToUse := inv
+	if methodInfo, ok := ghcontext.MCPMethod(r.Context()); ok && methodInfo != nil {
+		invToUse = inv.ForMCPRequest(methodInfo.Method, methodInfo.ItemName)
+	}
+
+	ghServer, err := h.githubMcpServerFactory(r, h.deps, invToUse, &github.MCPServerConfig{
 		Version:           h.config.Version,
 		Translator:        h.t,
 		ContentWindowSize: h.config.ContentWindowSize,
 		Logger:            h.logger,
 		RepoAccessTTL:     h.config.RepoAccessCacheTTL,
+		// Explicitly set empty capabilities. inv.ForMCPRequest currently returns nothing for Initialize.
+		ServerOptions: []github.MCPServerOption{
+			func(so *mcp.ServerOptions) {
+				so.Capabilities = &mcp.ServerCapabilities{
+					Tools:     &mcp.ToolCapabilities{},
+					Resources: &mcp.ResourceCapabilities{},
+					Prompts:   &mcp.PromptCapabilities{},
+				}
+			},
+		},
 	})
 
 	if err != nil {
 		w.WriteHeader(http.StatusInternalServerError)
+		return
 	}
 
 	mcpHandler := mcp.NewStreamableHTTPHandler(func(_ *http.Request) *mcp.Server {
@@ -177,13 +217,15 @@ func DefaultGitHubMCPServerFactory(r *http.Request, deps github.ToolDependencies
 }
 
 // DefaultInventoryFactory creates the default inventory factory for HTTP mode
-func DefaultInventoryFactory(_ *ServerConfig, t translations.TranslationHelperFunc, featureChecker inventory.FeatureFlagChecker) InventoryFactoryFunc {
+func DefaultInventoryFactory(_ *ServerConfig, t translations.TranslationHelperFunc, featureChecker inventory.FeatureFlagChecker, scopeFetcher scopes.FetcherInterface) InventoryFactoryFunc {
 	return func(r *http.Request) (*inventory.Inventory, error) {
 		b := github.NewInventory(t).
 			WithDeprecatedAliases(github.DeprecatedToolAliases).
 			WithFeatureChecker(featureChecker)
 
 		b = InventoryFiltersForRequest(r, b)
+		b = PATScopeFilter(b, r, scopeFetcher)
+
 		b.WithServerInstructions()
 
 		return b.Build()
@@ -215,3 +257,29 @@ func InventoryFiltersForRequest(r *http.Request, builder *inventory.Builder) *in
 
 	return builder
 }
+
+func PATScopeFilter(b *inventory.Builder, r *http.Request, fetcher scopes.FetcherInterface) *inventory.Builder {
+	ctx := r.Context()
+
+	tokenInfo, ok := ghcontext.GetTokenInfo(ctx)
+	if !ok || tokenInfo == nil {
+		return b
+	}
+
+	// Fetch token scopes for scope-based tool filtering (PAT tokens only)
+	// Only classic PATs (ghp_ prefix) return OAuth scopes via X-OAuth-Scopes header.
+	// Fine-grained PATs and other token types don't support this, so we skip filtering.
+	if tokenInfo.TokenType == utils.TokenTypePersonalAccessToken {
+		scopesList, err := fetcher.FetchTokenScopes(ctx, tokenInfo.Token)
+		if err != nil {
+			return b
+		}
+
+		// Store fetched scopes in context for downstream use
+		ghcontext.SetTokenScopes(ctx, scopesList)
+
+		return b.WithFilter(github.CreateToolScopeFilter(scopesList))
+	}
+
+	return b
+}