Skip to content

docs: add minimum PAT permissions for default toolsets #3049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
syf2211 wants to merge 1 commit into
base: main
Choose a base branch
from
+27 −1
Draft

docs: add minimum PAT permissions for default toolsets #3049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/installation-guides/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,18 @@ The GitHub MCP Server can be installed using several methods. **Docker is the mo
## General Prerequisites

All installations with Personal Access Tokens (PAT) require:
- **GitHub Personal Access Token (PAT)**: [Create one here](https://github.com/settings/personal-access-tokens/new)
- **GitHub Personal Access Token (PAT)**: [Create a fine-grained token](https://github.com/settings/personal-access-tokens/new) (recommended) or a [classic token](https://github.com/settings/tokens/new)

### Minimum token permissions

Use the smallest permission set that matches the toolsets you enable. The server starts with the **default** toolsets (`context`, `repos`, `issues`, `pull_requests`, `users`, `copilot`) unless you pass `--toolsets` or `GITHUB_TOOLSETS`.

| Token type | Minimum for default toolsets | Notes |
|------------|------------------------------|-------|
| **Fine-grained PAT** (recommended) | Repository access limited to the repos you need, with **Contents**, **Issues**, and **Pull requests** set to *Read and write* (Metadata: *Read* is added automatically) | Scopes are enforced by the GitHub API; the server cannot auto-hide tools for fine-grained tokens. See [PAT scope filtering](../scope-filtering.md#classic-vs-fine-grained-personal-access-tokens). |
| **Classic PAT** | `repo` (add `read:org` for org team/issue-type tools such as `get_teams`, `list_issue_types`) | Covers the default read/write repository, issue, and pull request tools. Add scopes only when enabling extra toolsets—for example `notifications` for the notifications toolset or `project` for projects. See the [scope filtering guide](../scope-filtering.md) and per-tool scope tables in the [README](../../README.md#tools). |

**Read-only deployments:** pass `--read-only` (or set `GITHUB_READ_ONLY=1`). For classic PATs, `public_repo` is enough for public repositories; private repository reads still need `repo`.

Optional (depending on installation method):
- **Docker** (for Docker-based installations): [Download Docker](https://www.docker.com/)
Expand Down
15 changes: 15 additions & 0 deletions docs/scope-filtering.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,21 @@ WARN: failed to fetch token scopes, continuing without scope filtering

**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.

### Minimum permissions (default toolsets)

When you run the server without custom `--toolsets`, the default set (`context`, `repos`, `issues`, `pull_requests`, `users`, `copilot`) needs repository read/write access for core issue/PR/file workflows:

| Token type | Grant |
|------------|-------|
| Fine-grained PAT | Limit repository access to the repos you need. Under **Repository permissions**, enable **Contents**, **Issues**, and **Pull requests** (Read and write). Org-scoped tools (`get_teams`, `list_issue_types`, …) may also need **Organization → Members** (Read). |
| Classic PAT | `repo` (add `read:org` if you use org team or issue-type tools in the default toolsets) |

Enable additional classic scopes only for non-default toolsets you turn on (for example `notifications`, `project`, `gist`). Each tool's required scopes are listed in the [README tool tables](../README.md#tools).

For read-only mode (`--read-only` / `GITHUB_READ_ONLY=1`), use the smallest read access that matches your repositories: `public_repo` for public repos only, or `repo` when private repositories must be readable.

See also the [installation prerequisites](./installation-guides/README.md#minimum-token-permissions) for links to the token-creation UI.

## GitHub App and Server-to-Server Tokens

**GitHub App installation tokens** (`ghs_` prefix) and other server-to-server tokens use a permission model based on the app's installation permissions rather than OAuth scopes. These tokens don't return the `X-OAuth-Scopes` header, so scope filtering is skipped. The GitHub API enforces permissions based on the app's configuration.
Expand Down