Only check scopes for classic PATs (ghp_ prefix)

- Scope filtering only applies to classic PATs which return X-OAuth-Scopes
- Fine-grained PATs and other token types skip filtering (all tools shown)
- Updated docs to clarify PAT filtering vs OAuth scope challenges

Author: SamMorrowDrums

docs/scope-filtering.md

@@ -1,13 +1,25 @@
-# OAuth Scope Filtering
+# PAT Scope Filtering
 
-The GitHub MCP Server automatically filters available tools based on your Personal Access Token's (PAT) OAuth scopes. This ensures you only see tools that your token has permission to use, reducing clutter and preventing errors from attempting operations your token can't perform.
+The GitHub MCP Server automatically filters available tools based on your classic Personal Access Token's (PAT) OAuth scopes. This ensures you only see tools that your token has permission to use, reducing clutter and preventing errors from attempting operations your token can't perform.
+
+> **Note:** This feature applies to **classic PATs** (tokens starting with `ghp_`). Fine-grained PATs and other token types don't support scope detection.
 
 ## How It Works
 
-When the server starts, it makes a lightweight HTTP HEAD request to the GitHub API to discover your token's scopes from the `X-OAuth-Scopes` header. Tools that require scopes your token doesn't have are automatically hidden.
+When the server starts with a classic PAT, it makes a lightweight HTTP HEAD request to the GitHub API to discover your token's scopes from the `X-OAuth-Scopes` header. Tools that require scopes your token doesn't have are automatically hidden.
 
 **Example:** If your token only has `repo` and `gist` scopes, you won't see tools that require `admin:org`, `project`, or `notifications` scopes.
 
+## PAT vs OAuth Authentication
+
+| Authentication | Scope Handling |
+|---------------|----------------|
+| **Classic PAT** (`ghp_`) | Filters tools at startup based on token scopes—tools requiring unavailable scopes are hidden |
+| **OAuth** (remote server only) | Uses OAuth scope challenges—when a tool needs a scope you haven't granted, you're prompted to authorize it |
+| **Fine-grained PAT** (`github_pat_`) | No filtering—all tools shown, API enforces permissions |
+
+With OAuth, the remote server can dynamically request additional scopes as needed. With PATs, scopes are fixed at token creation, so the server proactively hides tools you can't use.
+
 ## Checking Your Token's Scopes
 
 To see what scopes your token has, you can run:
@@ -70,9 +82,11 @@ If the server cannot fetch your token's scopes (e.g., network issues, rate limit
 WARN: failed to fetch token scopes, continuing without scope filtering
 ```
 
-## Fine-Grained Personal Access Tokens
+## Classic vs Fine-Grained Personal Access Tokens
+
+**Classic PATs** (`ghp_` prefix) support OAuth scopes and return them in the `X-OAuth-Scopes` header. Scope filtering works fully with these tokens.
 
-Fine-grained PATs use a different permission model and don't return OAuth scopes in the `X-OAuth-Scopes` header. When using fine-grained PATs, scope filtering will be skipped and all tools will be available. The GitHub API will still enforce permissions at the API level.
+**Fine-grained PATs** (`github_pat_` prefix) use a different permission model based on repository access and specific permissions rather than OAuth scopes. They don't return the `X-OAuth-Scopes` header, so scope filtering is skipped. All tools will be available, but the GitHub API will still enforce permissions at the API level—you'll get errors if you try to use tools your token doesn't have permission for.
 
 ## Troubleshooting
 

internal/ghmcp/server.go

@@ -350,14 +350,20 @@ func RunStdioServer(cfg StdioServerConfig) error {
 	logger := slog.New(slogHandler)
 	logger.Info("starting server", "version", cfg.Version, "host", cfg.Host, "dynamicToolsets", cfg.DynamicToolsets, "readOnly", cfg.ReadOnly, "lockdownEnabled", cfg.LockdownMode)
 
-	// Fetch token scopes for scope-based tool filtering
+	// 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.
 	var tokenScopes []string
-	fetchedScopes, err := fetchTokenScopesForHost(ctx, cfg.Token, cfg.Host)
-	if err != nil {
-		logger.Warn("failed to fetch token scopes, continuing without scope filtering", "error", err)
+	if strings.HasPrefix(cfg.Token, "ghp_") {
+		fetchedScopes, err := fetchTokenScopesForHost(ctx, cfg.Token, cfg.Host)
+		if err != nil {
+			logger.Warn("failed to fetch token scopes, continuing without scope filtering", "error", err)
+		} else {
+			tokenScopes = fetchedScopes
+			logger.Info("token scopes fetched for filtering", "scopes", tokenScopes)
+		}
 	} else {
-		tokenScopes = fetchedScopes
-		logger.Info("token scopes fetched for filtering", "scopes", tokenScopes)
+		logger.Debug("skipping scope filtering for non-PAT token")
 	}
 
 	ghServer, err := NewMCPServer(MCPServerConfig{