docs: add minimum PAT permissions for default toolsets

Document the smallest fine-grained and classic PAT permissions needed
for the default github-mcp-server toolsets, and link to the fine-grained
token creation UI.

Fixes #2963

Author: syf2211

docs/installation-guides/README.md

@@ -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/)

docs/scope-filtering.md

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