Skip to content

Commit e419a8c

Browse files
SamMorrowDrumsSamMorrowDrums
committed
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
1 parent e81f120 commit e419a8c

File tree

1 file changed

+149
-0
lines changed

1 file changed

+149
-0
lines changed

‎docs/changelog/2026-01-intelligent-scope-features.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: "Intelligent Scope Features"
3+
date: 2026-01
4+
description: "OAuth scope challenges, automatic PAT filtering, and comprehensive scope documentation for smarter authentication"
5+
category: feature
6+
---
7+
8+
# Intelligent Scope Features
9+
10+
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.
11+
12+
## What's New
13+
14+
### OAuth Scope Challenges (Remote Server)
15+
16+
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.
17+
18+
**How it works:**
19+
1. You attempt to use a tool that requires a scope you haven't granted
20+
2. The server returns a `401` with a `WWW-Authenticate` header indicating the missing scope
21+
3. Your MCP client (if supported) prompts you to authorize the additional scope
22+
4. After granting permission, the operation completes automatically
23+
24+
This means you can start with minimal permissions and expand them naturally as you use more features—no upfront "grant all permissions" prompts.
25+
26+
### PAT Scope Filtering (Local Server)
27+
28+
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.
29+
30+
**Benefits:**
31+
- **Reduced clutter** — Only see tools your token supports
32+
- **No failed calls** — Tools requiring unavailable scopes are hidden proactively
33+
- **Clear expectations** — Your tool list matches your actual capabilities
34+
35+
**Example:** If your PAT only has `repo` and `gist` scopes, tools requiring `admin:org`, `project`, or `notifications` will be hidden from your tool list.
36+
37+
### Documented OAuth Scopes
38+
39+
Every MCP tool now includes explicit OAuth scope documentation:
40+
41+
- **Required Scopes** — The minimum scope(s) needed to use the tool
42+
- **Accepted Scopes** — All scopes that satisfy the requirement (including parent scopes)
43+
44+
This information is visible in:
45+
- **README.md** — Each tool's documentation shows required and accepted scopes
46+
- **Tool metadata** — Available programmatically via the MCP protocol
47+
48+
**Example from README:**
49+
```
50+
### create_issue
51+
Creates a new issue in a GitHub repository.
52+
Required scopes: repo
53+
Accepted scopes: repo
54+
```
55+
56+
### New `list-scopes` Command
57+
58+
A new CLI command helps you understand what scopes your configured toolsets need:
59+
60+
```bash
61+
# See scopes for default toolsets
62+
github-mcp-server list-scopes --output=summary
63+
64+
# Output:
65+
# Required OAuth scopes for enabled tools:
66+
# read:org
67+
# repo
68+
# Total: 2 unique scope(s)
69+
70+
# All toolsets with detailed output
71+
github-mcp-server list-scopes --toolsets=all --output=text
72+
73+
# JSON for automation
74+
github-mcp-server list-scopes --output=json
75+
```
76+
77+
Use this to:
78+
- **Create minimal PATs** — Know exactly what scopes to grant
79+
- **Audit permissions** — Understand what each toolset requires
80+
- **CI/CD setup** — Generate scope lists programmatically
81+
82+
## Scope Hierarchy
83+
84+
The server understands GitHub's scope hierarchy, so parent scopes satisfy child scope requirements:
85+
86+
| Parent Scope | Covers |
87+
|-------------|--------|
88+
| `repo` | `public_repo`, `security_events` |
89+
| `admin:org` | `write:org`, `read:org` |
90+
| `project` | `read:project` |
91+
| `write:org` | `read:org` |
92+
93+
If a tool requires `read:org` and your token has `admin:org`, the tool is available.
94+
95+
## Authentication Comparison
96+
97+
| Authentication Method | Scope Handling |
98+
|----------------------|----------------|
99+
| **OAuth** (remote server) | Scope challenges — request permissions on-demand |
100+
| **Classic PAT** (`ghp_`) | Automatic filtering — hide unavailable tools |
101+
| **Fine-grained PAT** (`github_pat_`) | No filtering — API enforces permissions at call time |
102+
| **GitHub App** (`ghs_`) | No filtering — permissions based on app installation |
103+
104+
## Getting Started
105+
106+
### For Remote Server (OAuth) Users
107+
108+
No action required! Scope challenges work automatically with supporting MCP clients like VS Code. You'll be prompted for additional permissions as needed.
109+
110+
### For Local Server (PAT) Users
111+
112+
1. **Discover required scopes:**
113+
```bash
114+
github-mcp-server list-scopes --toolsets=repos,issues,pull_requests --output=summary
115+
```
116+
117+
2. **Create a PAT with those scopes** at [github.com/settings/tokens](https://github.com/settings/tokens)
118+
119+
3. **Start the server** — tools not supported by your token will be automatically hidden
120+
121+
### Checking Your Current Scopes
122+
123+
```bash
124+
curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
125+
https://api.github.com/user | grep -i x-oauth-scopes
126+
```
127+
128+
## Related Documentation
129+
130+
- [PAT Scope Filtering Guide](../scope-filtering.md)
131+
- [OAuth Authentication Guide](../oauth-authentication.md)
132+
- [Server Configuration](../server-configuration.md)
133+
134+
## Key PRs
135+
136+
**github-mcp-server:**
137+
- [#1679](https://github.com/github/github-mcp-server/pull/1679) — Add OAuth scope metadata to all MCP tools
138+
- [#1741](https://github.com/github/github-mcp-server/pull/1741) — Add PAT scope filtering for stdio server
139+
- [#1750](https://github.com/github/github-mcp-server/pull/1750) — Add `list-scopes` command using inventory architecture
140+
- [#1650](https://github.com/github/github-mcp-server/pull/1650) — OAuth scopes customization and documentation
141+
142+
**github-mcp-server-remote:**
143+
- [#503](https://github.com/github/github-mcp-server-remote/pull/503) — Dynamic scope challenges implementation
144+
- [#609](https://github.com/github/github-mcp-server-remote/pull/609) — Dynamic OAuth scopes based on route and headers
145+
- [#618](https://github.com/github/github-mcp-server-remote/pull/618) — Initialize tool scope map for scope challenge middleware
146+
147+
## What's Not Included
148+
149+
**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.

0 commit comments

Comments
 (0)