Make scope filtering always enabled (remove flag)

Scope filtering is now a built-in feature rather than a configurable option.
The server automatically fetches token scopes at startup and filters tools
accordingly. If scope detection fails, it logs a warning and continues with
all tools available.

Author: SamMorrowDrums

cmd/github-mcp-server/main.go

@@ -84,7 +84,6 @@ var (
 				ContentWindowSize:    viper.GetInt("content-window-size"),
 				LockdownMode:         viper.GetBool("lockdown-mode"),
 				RepoAccessCacheTTL:   &ttl,
-				EnableScopeFiltering: viper.GetBool("enable-scope-filtering"),
 			}
 			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
@@ -110,7 +109,6 @@ func init() {
 	rootCmd.PersistentFlags().Int("content-window-size", 5000, "Specify the content window size")
 	rootCmd.PersistentFlags().Bool("lockdown-mode", false, "Enable lockdown mode")
 	rootCmd.PersistentFlags().Duration("repo-access-cache-ttl", 5*time.Minute, "Override the repo access cache TTL (e.g. 1m, 0s to disable)")
-	rootCmd.PersistentFlags().Bool("enable-scope-filtering", true, "Filter tools based on the token's OAuth scopes")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -125,7 +123,6 @@ func init() {
 	_ = viper.BindPFlag("content-window-size", rootCmd.PersistentFlags().Lookup("content-window-size"))
 	_ = viper.BindPFlag("lockdown-mode", rootCmd.PersistentFlags().Lookup("lockdown-mode"))
 	_ = viper.BindPFlag("repo-access-cache-ttl", rootCmd.PersistentFlags().Lookup("repo-access-cache-ttl"))
-	_ = viper.BindPFlag("enable-scope-filtering", rootCmd.PersistentFlags().Lookup("enable-scope-filtering"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)

docs/scope-filtering.md

@@ -0,0 +1,89 @@
+# OAuth 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.
+
+## 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.
+
+**Example:** If your token only has `repo` and `gist` scopes, you won't see tools that require `admin:org`, `project`, or `notifications` scopes.
+
+## Checking Your Token's Scopes
+
+To see what scopes your token has, you can run:
+
+```bash
+curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
+  https://api.github.com/user | grep -i x-oauth-scopes
+```
+
+Example output:
+```
+x-oauth-scopes: delete_repo, gist, read:org, repo
+```
+
+## Scopes and Tools
+
+The following table shows which OAuth scopes are required for each category of tools:
+
+| Scope | Tools Enabled |
+|-------|---------------|
+| `repo` | Repository operations, issues, PRs, commits, branches, code search, workflows |
+| `public_repo` | Star/unstar public repositories (implicit with `repo`) |
+| `read:org` | Read organization info, list teams, team members |
+| `write:org` | Organization management (includes `read:org`) |
+| `admin:org` | Full organization administration (includes `write:org`, `read:org`) |
+| `gist` | Create, update, and manage gists |
+| `notifications` | List, manage, and dismiss notifications |
+| `read:project` | Read GitHub Projects |
+| `project` | Create and manage GitHub Projects (includes `read:project`) |
+| `security_events` | Code scanning, Dependabot, secret scanning alerts (implicit with `repo`) |
+| `user` | Update user profile |
+| `read:user` | Read user profile information |
+
+### Scope Hierarchy
+
+Some scopes implicitly include others:
+
+- `repo` → includes `public_repo`, `security_events`
+- `admin:org` → includes `write:org` → includes `read:org`
+- `project` → includes `read:project`
+
+This means if your token has `repo`, tools requiring `security_events` will also be available.
+
+## Recommended Token Scopes
+
+For full functionality, we recommend these scopes:
+
+| Use Case | Recommended Scopes |
+|----------|-------------------|
+| Basic development | `repo`, `read:org` |
+| Full development | `repo`, `admin:org`, `gist`, `notifications`, `project` |
+| Read-only access | `repo` (with `--read-only` flag) |
+| Security analysis | `repo` (includes `security_events`) |
+
+## Graceful Degradation
+
+If the server cannot fetch your token's scopes (e.g., network issues, rate limiting), it logs a warning and continues **without filtering**. This ensures the server remains usable even when scope detection fails.
+
+```
+WARN: failed to fetch token scopes, continuing without scope filtering
+```
+
+## Fine-Grained Personal Access 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.
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| Missing expected tools | Token lacks required scope | Add the scope to your PAT |
+| All tools visible despite limited PAT | Scope detection failed | Check logs for warnings about scope fetching |
+| "Insufficient permissions" errors | Tool visible but scope insufficient | This shouldn't happen with scope filtering; report as bug |
+
+## Related Documentation
+
+- [Server Configuration Guide](./server-configuration.md)
+- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+- [OAuth Scopes Reference](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)

docs/server-configuration.md

@@ -12,6 +12,7 @@ We currently support the following ways in which the GitHub MCP Server can be co
 | Read-Only Mode | `X-MCP-Readonly` header or `/readonly` URL | `--read-only` flag or `GITHUB_READ_ONLY` env var |
 | Dynamic Mode | Not available | `--dynamic-toolsets` flag or `GITHUB_DYNAMIC_TOOLSETS` env var |
 | Lockdown Mode | `X-MCP-Lockdown` header | `--lockdown-mode` flag or `GITHUB_LOCKDOWN_MODE` env var |
+| Scope Filtering | Always enabled | Always enabled |
 
 > **Default behavior:** If you don't specify any configuration, the server uses the **default toolsets**: `context`, `issues`, `pull_requests`, `repos`, `users`.
 
@@ -330,6 +331,16 @@ Lockdown mode ensures the server only surfaces content in public repositories fr
 
 ---
 
+### Scope Filtering
+
+**Automatic feature:** The server automatically detects your PAT's OAuth scopes and only shows tools you have permission to use.
+
+This happens transparently at startup - no configuration needed. If scope detection fails (e.g., network issues), the server logs a warning and continues with all tools available.
+
+See [OAuth Scope Filtering](./scope-filtering.md) for details on which scopes enable which tools.
+
+---
+
 ## Troubleshooting
 
 | Problem | Cause | Solution |

internal/ghmcp/server.go

@@ -324,11 +324,6 @@ type StdioServerConfig struct {
 
 	// RepoAccessCacheTTL overrides the default TTL for repository access cache entries.
 	RepoAccessCacheTTL *time.Duration
-
-	// EnableScopeFiltering enables PAT scope-based tool filtering.
-	// When true, the server will fetch the token's OAuth scopes at startup
-	// and hide tools that require scopes the token doesn't have.
-	EnableScopeFiltering bool
 }
 
 // RunStdioServer is not concurrent safe.
@@ -353,18 +348,16 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		slogHandler = slog.NewTextHandler(logOutput, &slog.HandlerOptions{Level: slog.LevelInfo})
 	}
 	logger := slog.New(slogHandler)
-	logger.Info("starting server", "version", cfg.Version, "host", cfg.Host, "dynamicToolsets", cfg.DynamicToolsets, "readOnly", cfg.ReadOnly, "lockdownEnabled", cfg.LockdownMode, "scopeFiltering", cfg.EnableScopeFiltering)
+	logger.Info("starting server", "version", cfg.Version, "host", cfg.Host, "dynamicToolsets", cfg.DynamicToolsets, "readOnly", cfg.ReadOnly, "lockdownEnabled", cfg.LockdownMode)
 
-	// Fetch token scopes if scope filtering is enabled
+	// Fetch token scopes for scope-based tool filtering
 	var tokenScopes []string
-	if cfg.EnableScopeFiltering {
-		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)
-		}
+	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)
 	}
 
 	ghServer, err := NewMCPServer(MCPServerConfig{