From 4deaa8321ecaa2a6843e08a1fc49eb9f7092a149 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 5 Jan 2026 14:54:12 +0100 Subject: [PATCH] Remove empty filter.go and document OAuth scope challenges --- docs/scope-filtering.md | 12 ++++++++++++ pkg/scopes/filter.go | 7 ------- 2 files changed, 12 insertions(+), 7 deletions(-) delete mode 100644 pkg/scopes/filter.go diff --git a/docs/scope-filtering.md b/docs/scope-filtering.md index 979a4d59..c40bf729 100644 --- a/docs/scope-filtering.md +++ b/docs/scope-filtering.md @@ -22,6 +22,18 @@ When the server starts with a classic PAT, it makes a lightweight HTTP HEAD requ 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. +## OAuth Scope Challenges (Remote Server) + +When using the [remote MCP server](./remote-server.md) with OAuth authentication, the server uses a different approach called **scope challenges**. Instead of hiding tools upfront, all tools are available, and the server requests additional scopes on-demand when you try to use a tool that requires them. + +**How it works:** +1. You attempt to use a tool (e.g., creating an issue) +2. If your current OAuth token lacks the required scope, the server returns an OAuth scope challenge +3. Your MCP client prompts you to authorize the additional scope +4. After authorization, the operation completes successfully + +This provides a smoother user experience for OAuth users since you only grant permissions as needed, rather than requesting all scopes upfront. + ## Checking Your Token's Scopes To see what scopes your token has, you can run: diff --git a/pkg/scopes/filter.go b/pkg/scopes/filter.go deleted file mode 100644 index 3eb3457a..00000000 --- a/pkg/scopes/filter.go +++ /dev/null @@ -1,7 +0,0 @@ -// Package scopes provides OAuth scope checking utilities for GitHub MCP Server. -// -// This file contains utilities for filtering tools based on token scopes. -// For PATs, we cannot issue OAuth scope challenges, so we hide tools that -// require scopes the token doesn't have. -// -package scopes