From e419a8cc572337043c814296072a6f8bcdc8f748 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 22:52:12 +0100 Subject: [PATCH 1/9] docs: Add changelog for intelligent scope features Documents the new OAuth scope handling capabilities including: - OAuth scope challenges (MCP step-up auth) for remote server - PAT scope filtering for local/stdio server - Documented scopes for all MCP tools - New list-scopes CLI command Related PRs: - github-mcp-server: #1679, #1741, #1750, #1650 - github-mcp-server-remote: #503, #609, #618 --- .../2026-01-intelligent-scope-features.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/changelog/2026-01-intelligent-scope-features.md diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md new file mode 100644 index 000000000..bbc3ab999 --- /dev/null +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -0,0 +1,149 @@ +--- +title: "Intelligent Scope Features" +date: 2026-01 +description: "OAuth scope challenges, automatic PAT filtering, and comprehensive scope documentation for smarter authentication" +category: feature +--- + +# Intelligent Scope Features + +GitHub MCP Server now provides intelligent handling of OAuth scopes across all authentication methods—automatically filtering tools based on your permissions and enabling dynamic scope requests when needed. + +## What's New + +### OAuth Scope Challenges (Remote Server) + +When using the remote MCP server with OAuth authentication (like VS Code's GitHub Copilot Chat), the server now implements the [MCP step-up authentication specification](https://spec.modelcontextprotocol.io/). Instead of failing when you lack a required scope, the server can request additional permissions dynamically. + +**How it works:** +1. You attempt to use a tool that requires a scope you haven't granted +2. The server returns a `401` with a `WWW-Authenticate` header indicating the missing scope +3. Your MCP client (if supported) prompts you to authorize the additional scope +4. After granting permission, the operation completes automatically + +This means you can start with minimal permissions and expand them naturally as you use more features—no upfront "grant all permissions" prompts. + +### PAT Scope Filtering (Local Server) + +For users running the local server with a classic Personal Access Token (`ghp_` prefix), tools are now automatically filtered based on your token's scopes. At startup, the server discovers your token's scopes and hides tools you can't use. + +**Benefits:** +- **Reduced clutter** — Only see tools your token supports +- **No failed calls** — Tools requiring unavailable scopes are hidden proactively +- **Clear expectations** — Your tool list matches your actual capabilities + +**Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` will be hidden from your tool list. + +### Documented OAuth Scopes + +Every MCP tool now includes explicit OAuth scope documentation: + +- **Required Scopes** — The minimum scope(s) needed to use the tool +- **Accepted Scopes** — All scopes that satisfy the requirement (including parent scopes) + +This information is visible in: +- **README.md** — Each tool's documentation shows required and accepted scopes +- **Tool metadata** — Available programmatically via the MCP protocol + +**Example from README:** +``` +### create_issue +Creates a new issue in a GitHub repository. +Required scopes: repo +Accepted scopes: repo +``` + +### New `list-scopes` Command + +A new CLI command helps you understand what scopes your configured toolsets need: + +```bash +# See scopes for default toolsets +github-mcp-server list-scopes --output=summary + +# Output: +# Required OAuth scopes for enabled tools: +# read:org +# repo +# Total: 2 unique scope(s) + +# All toolsets with detailed output +github-mcp-server list-scopes --toolsets=all --output=text + +# JSON for automation +github-mcp-server list-scopes --output=json +``` + +Use this to: +- **Create minimal PATs** — Know exactly what scopes to grant +- **Audit permissions** — Understand what each toolset requires +- **CI/CD setup** — Generate scope lists programmatically + +## Scope Hierarchy + +The server understands GitHub's scope hierarchy, so parent scopes satisfy child scope requirements: + +| Parent Scope | Covers | +|-------------|--------| +| `repo` | `public_repo`, `security_events` | +| `admin:org` | `write:org`, `read:org` | +| `project` | `read:project` | +| `write:org` | `read:org` | + +If a tool requires `read:org` and your token has `admin:org`, the tool is available. + +## Authentication Comparison + +| Authentication Method | Scope Handling | +|----------------------|----------------| +| **OAuth** (remote server) | Scope challenges — request permissions on-demand | +| **Classic PAT** (`ghp_`) | Automatic filtering — hide unavailable tools | +| **Fine-grained PAT** (`github_pat_`) | No filtering — API enforces permissions at call time | +| **GitHub App** (`ghs_`) | No filtering — permissions based on app installation | + +## Getting Started + +### For Remote Server (OAuth) Users + +No action required! Scope challenges work automatically with supporting MCP clients like VS Code. You'll be prompted for additional permissions as needed. + +### For Local Server (PAT) Users + +1. **Discover required scopes:** + ```bash + github-mcp-server list-scopes --toolsets=repos,issues,pull_requests --output=summary + ``` + +2. **Create a PAT with those scopes** at [github.com/settings/tokens](https://github.com/settings/tokens) + +3. **Start the server** — tools not supported by your token will be automatically hidden + +### Checking Your Current Scopes + +```bash +curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \ + https://api.github.com/user | grep -i x-oauth-scopes +``` + +## Related Documentation + +- [PAT Scope Filtering Guide](../scope-filtering.md) +- [OAuth Authentication Guide](../oauth-authentication.md) +- [Server Configuration](../server-configuration.md) + +## Key PRs + +**github-mcp-server:** +- [#1679](https://github.com/github/github-mcp-server/pull/1679) — Add OAuth scope metadata to all MCP tools +- [#1741](https://github.com/github/github-mcp-server/pull/1741) — Add PAT scope filtering for stdio server +- [#1750](https://github.com/github/github-mcp-server/pull/1750) — Add `list-scopes` command using inventory architecture +- [#1650](https://github.com/github/github-mcp-server/pull/1650) — OAuth scopes customization and documentation + +**github-mcp-server-remote:** +- [#503](https://github.com/github/github-mcp-server-remote/pull/503) — Dynamic scope challenges implementation +- [#609](https://github.com/github/github-mcp-server-remote/pull/609) — Dynamic OAuth scopes based on route and headers +- [#618](https://github.com/github/github-mcp-server-remote/pull/618) — Initialize tool scope map for scope challenge middleware + +## What's Not Included + +**Fine-grained PAT support** — Fine-grained Personal Access Tokens use a different permission model based on repository access rather than OAuth scopes. They don't return an `X-OAuth-Scopes` header, so scope filtering and scope challenges don't apply. The GitHub API enforces permissions at call time, and you'll receive clear error messages if an operation isn't permitted. From b94ada5ca2c166a27b96b223bd0005498f5b6be2 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 22:55:10 +0100 Subject: [PATCH 2/9] docs: Add server-to-server token handling and feedback link - Document S2S token filtering (hiding user tools like get_me) - Add S2S row to authentication comparison table - Link to discussion #1802 for feedback --- .../2026-01-intelligent-scope-features.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index bbc3ab999..860dbc771 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -34,6 +34,16 @@ For users running the local server with a classic Personal Access Token (`ghp_` **Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` will be hidden from your tool list. +### Server-to-Server Token Handling (Remote Server) + +When using server-to-server tokens (like the `GITHUB_TOKEN` in GitHub Actions), the remote server now intelligently hides user-context tools that don't make sense without a human user. + +**Tools hidden for S2S tokens:** +- `get_me` — No user to query +- Other user-specific context tools + +This ensures automated workflows see only the tools they can actually use, rather than failing when they attempt to call user-context APIs. + ### Documented OAuth Scopes Every MCP tool now includes explicit OAuth scope documentation: @@ -100,6 +110,7 @@ If a tool requires `read:org` and your token has `admin:org`, the tool is availa | **Classic PAT** (`ghp_`) | Automatic filtering — hide unavailable tools | | **Fine-grained PAT** (`github_pat_`) | No filtering — API enforces permissions at call time | | **GitHub App** (`ghs_`) | No filtering — permissions based on app installation | +| **Server-to-Server** (`GITHUB_TOKEN`) | User tools hidden — no user context available | ## Getting Started @@ -131,6 +142,10 @@ curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \ - [OAuth Authentication Guide](../oauth-authentication.md) - [Server Configuration](../server-configuration.md) +## Feedback + +Share your experience and report issues in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). + ## Key PRs **github-mcp-server:** From 772bb09720f672b8bed15aa1c15e916227509846 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 22:57:07 +0100 Subject: [PATCH 3/9] docs: Fix MCP spec link and clarify PAT filtering scope - Use November 2025 spec link with correct anchor - Clarify PAT filtering works on both local and remote server --- docs/changelog/2026-01-intelligent-scope-features.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index 860dbc771..de03313da 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -13,7 +13,7 @@ GitHub MCP Server now provides intelligent handling of OAuth scopes across all a ### OAuth Scope Challenges (Remote Server) -When using the remote MCP server with OAuth authentication (like VS Code's GitHub Copilot Chat), the server now implements the [MCP step-up authentication specification](https://spec.modelcontextprotocol.io/). Instead of failing when you lack a required scope, the server can request additional permissions dynamically. +When using the remote MCP server with OAuth authentication (like VS Code's GitHub Copilot Chat), the server now implements the [MCP scope challenge handling specification](https://modelcontextprotocol.io/specification/2025-11-05/basic/authorization#scope-challenge-handling). Instead of failing when you lack a required scope, the server can request additional permissions dynamically. **How it works:** 1. You attempt to use a tool that requires a scope you haven't granted @@ -23,9 +23,9 @@ When using the remote MCP server with OAuth authentication (like VS Code's GitHu This means you can start with minimal permissions and expand them naturally as you use more features—no upfront "grant all permissions" prompts. -### PAT Scope Filtering (Local Server) +### PAT Scope Filtering -For users running the local server with a classic Personal Access Token (`ghp_` prefix), tools are now automatically filtered based on your token's scopes. At startup, the server discovers your token's scopes and hides tools you can't use. +For users authenticating with a classic Personal Access Token (`ghp_` prefix), tools are now automatically filtered based on your token's scopes. At startup, the server discovers your token's scopes and hides tools you can't use. This works on both the local (stdio) and remote server. **Benefits:** - **Reduced clutter** — Only see tools your token supports From 1d83e141dbb9adfbe3f8f0a361f153975266c917 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 22:59:40 +0100 Subject: [PATCH 4/9] docs: Use absolute URLs for related documentation links --- docs/changelog/2026-01-intelligent-scope-features.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index de03313da..cedea9ad6 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -138,9 +138,9 @@ curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \ ## Related Documentation -- [PAT Scope Filtering Guide](../scope-filtering.md) -- [OAuth Authentication Guide](../oauth-authentication.md) -- [Server Configuration](../server-configuration.md) +- [PAT Scope Filtering Guide](https://github.com/github/github-mcp-server/blob/main/docs/scope-filtering.md) +- [OAuth Authentication Guide](https://github.com/github/github-mcp-server/blob/main/docs/oauth-authentication.md) +- [Server Configuration](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md) ## Feedback From 2c7fd777d82f4e075a1484eaa0f4c058da6253dd Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 23:02:05 +0100 Subject: [PATCH 5/9] chore: use stable v0.29.0 tag URLs for related documentation --- docs/changelog/2026-01-intelligent-scope-features.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index cedea9ad6..f52158568 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -138,9 +138,9 @@ curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \ ## Related Documentation -- [PAT Scope Filtering Guide](https://github.com/github/github-mcp-server/blob/main/docs/scope-filtering.md) -- [OAuth Authentication Guide](https://github.com/github/github-mcp-server/blob/main/docs/oauth-authentication.md) -- [Server Configuration](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md) +- [PAT Scope Filtering Guide](https://github.com/github/github-mcp-server/blob/v0.29.0/docs/scope-filtering.md) +- [OAuth Authentication Guide](https://github.com/github/github-mcp-server/blob/v0.29.0/docs/oauth-authentication.md) +- [Server Configuration](https://github.com/github/github-mcp-server/blob/v0.29.0/docs/server-configuration.md) ## Feedback From 629846c22554224176805e9a2f3def444f9065b4 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 23:03:28 +0100 Subject: [PATCH 6/9] chore: tighten changelog, remove PRs, clarify fine-grained permissions --- .../2026-01-intelligent-scope-features.md | 110 +++--------------- 1 file changed, 14 insertions(+), 96 deletions(-) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index f52158568..5a7850094 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -7,88 +7,37 @@ category: feature # Intelligent Scope Features -GitHub MCP Server now provides intelligent handling of OAuth scopes across all authentication methods—automatically filtering tools based on your permissions and enabling dynamic scope requests when needed. +GitHub MCP Server now intelligently handles OAuth scopes—filtering tools based on your permissions and enabling dynamic scope requests when needed. ## What's New ### OAuth Scope Challenges (Remote Server) -When using the remote MCP server with OAuth authentication (like VS Code's GitHub Copilot Chat), the server now implements the [MCP scope challenge handling specification](https://modelcontextprotocol.io/specification/2025-11-05/basic/authorization#scope-challenge-handling). Instead of failing when you lack a required scope, the server can request additional permissions dynamically. - -**How it works:** -1. You attempt to use a tool that requires a scope you haven't granted -2. The server returns a `401` with a `WWW-Authenticate` header indicating the missing scope -3. Your MCP client (if supported) prompts you to authorize the additional scope -4. After granting permission, the operation completes automatically - -This means you can start with minimal permissions and expand them naturally as you use more features—no upfront "grant all permissions" prompts. +The remote server now implements [MCP scope challenge handling](https://modelcontextprotocol.io/specification/2025-11-05/basic/authorization#scope-challenge-handling). Instead of failing when you lack a required scope, it requests additional permissions dynamically—start with minimal permissions and expand them as needed. ### PAT Scope Filtering -For users authenticating with a classic Personal Access Token (`ghp_` prefix), tools are now automatically filtered based on your token's scopes. At startup, the server discovers your token's scopes and hides tools you can't use. This works on both the local (stdio) and remote server. +For classic Personal Access Tokens (`ghp_` prefix), tools are automatically filtered based on your token's scopes. The server discovers your scopes at startup and hides tools you can't use. -**Benefits:** -- **Reduced clutter** — Only see tools your token supports -- **No failed calls** — Tools requiring unavailable scopes are hidden proactively -- **Clear expectations** — Your tool list matches your actual capabilities - -**Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` will be hidden from your tool list. +**Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` are hidden. ### Server-to-Server Token Handling (Remote Server) -When using server-to-server tokens (like the `GITHUB_TOKEN` in GitHub Actions), the remote server now intelligently hides user-context tools that don't make sense without a human user. - -**Tools hidden for S2S tokens:** -- `get_me` — No user to query -- Other user-specific context tools - -This ensures automated workflows see only the tools they can actually use, rather than failing when they attempt to call user-context APIs. +For server-to-server tokens (like `GITHUB_TOKEN` in Actions), the remote server hides user-context tools like `get_me` that don't apply without a human user. ### Documented OAuth Scopes -Every MCP tool now includes explicit OAuth scope documentation: - -- **Required Scopes** — The minimum scope(s) needed to use the tool -- **Accepted Scopes** — All scopes that satisfy the requirement (including parent scopes) - -This information is visible in: -- **README.md** — Each tool's documentation shows required and accepted scopes -- **Tool metadata** — Available programmatically via the MCP protocol - -**Example from README:** -``` -### create_issue -Creates a new issue in a GitHub repository. -Required scopes: repo -Accepted scopes: repo -``` +Every MCP tool now documents its required and accepted OAuth scopes in the README and tool metadata. ### New `list-scopes` Command -A new CLI command helps you understand what scopes your configured toolsets need: +Discover what scopes your toolsets need: ```bash -# See scopes for default toolsets github-mcp-server list-scopes --output=summary - -# Output: -# Required OAuth scopes for enabled tools: -# read:org -# repo -# Total: 2 unique scope(s) - -# All toolsets with detailed output -github-mcp-server list-scopes --toolsets=all --output=text - -# JSON for automation -github-mcp-server list-scopes --output=json +github-mcp-server list-scopes --toolsets=all --output=json ``` -Use this to: -- **Create minimal PATs** — Know exactly what scopes to grant -- **Audit permissions** — Understand what each toolset requires -- **CI/CD setup** — Generate scope lists programmatically - ## Scope Hierarchy The server understands GitHub's scope hierarchy, so parent scopes satisfy child scope requirements: @@ -108,33 +57,15 @@ If a tool requires `read:org` and your token has `admin:org`, the tool is availa |----------------------|----------------| | **OAuth** (remote server) | Scope challenges — request permissions on-demand | | **Classic PAT** (`ghp_`) | Automatic filtering — hide unavailable tools | -| **Fine-grained PAT** (`github_pat_`) | No filtering — API enforces permissions at call time | -| **GitHub App** (`ghs_`) | No filtering — permissions based on app installation | +| **Fine-grained PAT** (`github_pat_`) | No filtering — fine-grained permissions, not OAuth scopes | +| **GitHub App** (`ghs_`) | No filtering — fine-grained permissions, not OAuth scopes | | **Server-to-Server** (`GITHUB_TOKEN`) | User tools hidden — no user context available | ## Getting Started -### For Remote Server (OAuth) Users - -No action required! Scope challenges work automatically with supporting MCP clients like VS Code. You'll be prompted for additional permissions as needed. - -### For Local Server (PAT) Users - -1. **Discover required scopes:** - ```bash - github-mcp-server list-scopes --toolsets=repos,issues,pull_requests --output=summary - ``` - -2. **Create a PAT with those scopes** at [github.com/settings/tokens](https://github.com/settings/tokens) - -3. **Start the server** — tools not supported by your token will be automatically hidden +**OAuth users:** No action required—scope challenges work automatically. -### Checking Your Current Scopes - -```bash -curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \ - https://api.github.com/user | grep -i x-oauth-scopes -``` +**PAT users:** Run `list-scopes` to discover required scopes, create a PAT at [github.com/settings/tokens](https://github.com/settings/tokens), and start the server. ## Related Documentation @@ -144,21 +75,8 @@ curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \ ## Feedback -Share your experience and report issues in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). - -## Key PRs - -**github-mcp-server:** -- [#1679](https://github.com/github/github-mcp-server/pull/1679) — Add OAuth scope metadata to all MCP tools -- [#1741](https://github.com/github/github-mcp-server/pull/1741) — Add PAT scope filtering for stdio server -- [#1750](https://github.com/github/github-mcp-server/pull/1750) — Add `list-scopes` command using inventory architecture -- [#1650](https://github.com/github/github-mcp-server/pull/1650) — OAuth scopes customization and documentation - -**github-mcp-server-remote:** -- [#503](https://github.com/github/github-mcp-server-remote/pull/503) — Dynamic scope challenges implementation -- [#609](https://github.com/github/github-mcp-server-remote/pull/609) — Dynamic OAuth scopes based on route and headers -- [#618](https://github.com/github/github-mcp-server-remote/pull/618) — Initialize tool scope map for scope challenge middleware +Share your experience in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). ## What's Not Included -**Fine-grained PAT support** — Fine-grained Personal Access Tokens use a different permission model based on repository access rather than OAuth scopes. They don't return an `X-OAuth-Scopes` header, so scope filtering and scope challenges don't apply. The GitHub API enforces permissions at call time, and you'll receive clear error messages if an operation isn't permitted. +**Fine-grained permissions** — Fine-grained PATs (`github_pat_`) and GitHub Apps (`ghs_`) use repository-based permissions rather than OAuth scopes. They don't return `X-OAuth-Scopes` headers, so scope filtering and scope challenges don't apply. The API enforces permissions at call time. From 2e191426731e19e273bfc650086daffef5d23c07 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 23:04:23 +0100 Subject: [PATCH 7/9] chore: remove What's Not Included section, add future note --- docs/changelog/2026-01-intelligent-scope-features.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index 5a7850094..1ae89c610 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -77,6 +77,4 @@ If a tool requires `read:org` and your token has `admin:org`, the tool is availa Share your experience in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). -## What's Not Included - -**Fine-grained permissions** — Fine-grained PATs (`github_pat_`) and GitHub Apps (`ghs_`) use repository-based permissions rather than OAuth scopes. They don't return `X-OAuth-Scopes` headers, so scope filtering and scope challenges don't apply. The API enforces permissions at call time. +We're exploring ways to better support fine-grained permissions in the future. From 6cacd4496f8122b790fe530731450f0c20b0a5aa Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 23:31:15 +0100 Subject: [PATCH 8/9] chore: final editorial polish --- .../2026-01-intelligent-scope-features.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md index 1ae89c610..19e3852ea 100644 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ b/docs/changelog/2026-01-intelligent-scope-features.md @@ -11,19 +11,19 @@ GitHub MCP Server now intelligently handles OAuth scopes—filtering tools based ## What's New -### OAuth Scope Challenges (Remote Server) +### OAuth Scope Challenges -The remote server now implements [MCP scope challenge handling](https://modelcontextprotocol.io/specification/2025-11-05/basic/authorization#scope-challenge-handling). Instead of failing when you lack a required scope, it requests additional permissions dynamically—start with minimal permissions and expand them as needed. +The server now implements [MCP scope challenge handling](https://modelcontextprotocol.io/specification/2025-11-05/basic/authorization#scope-challenge-handling). Instead of failing when you lack a required scope, it requests additional permissions dynamically—start with minimal permissions and expand them as needed. ### PAT Scope Filtering -For classic Personal Access Tokens (`ghp_` prefix), tools are automatically filtered based on your token's scopes. The server discovers your scopes at startup and hides tools you can't use. +For classic Personal Access Tokens (`ghp_`), tools are automatically filtered based on your token's scopes. The server discovers your scopes at startup and hides tools you can't use. **Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` are hidden. -### Server-to-Server Token Handling (Remote Server) +### Server-to-Server Token Handling -For server-to-server tokens (like `GITHUB_TOKEN` in Actions), the remote server hides user-context tools like `get_me` that don't apply without a human user. +For server-to-server tokens (like `GITHUB_TOKEN` in Actions), the server hides user-context tools like `get_me` that don't apply without a human user. ### Documented OAuth Scopes @@ -75,6 +75,4 @@ If a tool requires `read:org` and your token has `admin:org`, the tool is availa ## Feedback -Share your experience in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). - -We're exploring ways to better support fine-grained permissions in the future. +Share your experience in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). We're exploring ways to better support fine-grained permissions in the future. From f39ea6c1a5391660c2ffd22a6dd8c1218a54af07 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 19 Jan 2026 23:37:21 +0100 Subject: [PATCH 9/9] Delete docs/changelog/2026-01-intelligent-scope-features.md --- .../2026-01-intelligent-scope-features.md | 78 ------------------- 1 file changed, 78 deletions(-) delete mode 100644 docs/changelog/2026-01-intelligent-scope-features.md diff --git a/docs/changelog/2026-01-intelligent-scope-features.md b/docs/changelog/2026-01-intelligent-scope-features.md deleted file mode 100644 index 19e3852ea..000000000 --- a/docs/changelog/2026-01-intelligent-scope-features.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Intelligent Scope Features" -date: 2026-01 -description: "OAuth scope challenges, automatic PAT filtering, and comprehensive scope documentation for smarter authentication" -category: feature ---- - -# Intelligent Scope Features - -GitHub MCP Server now intelligently handles OAuth scopes—filtering tools based on your permissions and enabling dynamic scope requests when needed. - -## What's New - -### OAuth Scope Challenges - -The server now implements [MCP scope challenge handling](https://modelcontextprotocol.io/specification/2025-11-05/basic/authorization#scope-challenge-handling). Instead of failing when you lack a required scope, it requests additional permissions dynamically—start with minimal permissions and expand them as needed. - -### PAT Scope Filtering - -For classic Personal Access Tokens (`ghp_`), tools are automatically filtered based on your token's scopes. The server discovers your scopes at startup and hides tools you can't use. - -**Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` are hidden. - -### Server-to-Server Token Handling - -For server-to-server tokens (like `GITHUB_TOKEN` in Actions), the server hides user-context tools like `get_me` that don't apply without a human user. - -### Documented OAuth Scopes - -Every MCP tool now documents its required and accepted OAuth scopes in the README and tool metadata. - -### New `list-scopes` Command - -Discover what scopes your toolsets need: - -```bash -github-mcp-server list-scopes --output=summary -github-mcp-server list-scopes --toolsets=all --output=json -``` - -## Scope Hierarchy - -The server understands GitHub's scope hierarchy, so parent scopes satisfy child scope requirements: - -| Parent Scope | Covers | -|-------------|--------| -| `repo` | `public_repo`, `security_events` | -| `admin:org` | `write:org`, `read:org` | -| `project` | `read:project` | -| `write:org` | `read:org` | - -If a tool requires `read:org` and your token has `admin:org`, the tool is available. - -## Authentication Comparison - -| Authentication Method | Scope Handling | -|----------------------|----------------| -| **OAuth** (remote server) | Scope challenges — request permissions on-demand | -| **Classic PAT** (`ghp_`) | Automatic filtering — hide unavailable tools | -| **Fine-grained PAT** (`github_pat_`) | No filtering — fine-grained permissions, not OAuth scopes | -| **GitHub App** (`ghs_`) | No filtering — fine-grained permissions, not OAuth scopes | -| **Server-to-Server** (`GITHUB_TOKEN`) | User tools hidden — no user context available | - -## Getting Started - -**OAuth users:** No action required—scope challenges work automatically. - -**PAT users:** Run `list-scopes` to discover required scopes, create a PAT at [github.com/settings/tokens](https://github.com/settings/tokens), and start the server. - -## Related Documentation - -- [PAT Scope Filtering Guide](https://github.com/github/github-mcp-server/blob/v0.29.0/docs/scope-filtering.md) -- [OAuth Authentication Guide](https://github.com/github/github-mcp-server/blob/v0.29.0/docs/oauth-authentication.md) -- [Server Configuration](https://github.com/github/github-mcp-server/blob/v0.29.0/docs/server-configuration.md) - -## Feedback - -Share your experience in the [Scope filtering/challenging discussion](https://github.com/github/github-mcp-server/discussions/1802). We're exploring ways to better support fine-grained permissions in the future.