MCP scopes control which tool categories are available during a session. When ChatGPT connects to the MCP server, the access token it holds carries a set of granted scopes. Any tool call whose category is not covered by the token’s scopes is rejected before the tool runs. Scopes are granted at the authorization/token issuance step — narrowing them before ChatGPT connects is the most effective way to limit what a session can do.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/chatgpt-local-agent-mcp/llms.txt
Use this file to discover all available pages before exploring further.
The Ten Scopes
The following scopes come directly fromsrc/scopes.ts. Every tool registered by the server falls under exactly one of these categories.
| Scope | Tools gated | Risk level |
|---|---|---|
mcp:read | read_file, stat, tree, search, hash, directory listing | 🟢 Low — read-only filesystem inspection |
mcp:write | write_file, mkdir, copy, move, rollback_backup | 🟡 Medium — creates and overwrites files |
mcp:shell | Shell command execution | 🔴 High — runs arbitrary commands |
mcp:git | git_status, git_diff, git_commit | 🟡 Medium — reads repo state, can commit |
mcp:patch | apply_patch | 🟡 Medium — modifies files via patch |
mcp:delete | delete (files and directories) | 🔴 High — permanent removal |
mcp:process | Process list/start/stop/kill, port list, tail_log, wait_for_port | 🔴 High — controls running processes |
mcp:screen | window_list, screen_screenshot, screen_ocr | 🟡 Medium — reads screen content |
mcp:desktop | Desktop mouse and keyboard automation tools | 🔴 High — full desktop input control |
mcp:browser | All browser automation tools (navigation, snapshots, CDP, screenshots, console, network) | 🔴 High — interacts with live browser sessions |
Risk levels reflect the potential blast radius if ChatGPT uses the scope incorrectly or if an attacker obtains the access token.
mcp:read alone can still expose sensitive files if workspace profiles are not configured carefully — see Security Boundaries.Controlling Default Scopes
TheDEFAULT_OAUTH_SCOPES environment variable controls which scopes are included by default when a ChatGPT authorization request does not explicitly request a specific scope list.
DEFAULT_OAUTH_SCOPES is not set, the server falls back to all scopes — every tool category is available. This is the full-power default. For anything other than initial exploration, set this explicitly.
Recommended: Start Narrow
Only grant the scopes a session actually needs. You can always reconnect with broader scopes when a task requires it.Read-only code review session
Inspect files, check git status and diffs. No writes, no shell, no browser.
Filesystem editing session
Read and write files, apply patches, manage git. No shell or browser.
Diagnostics session
Read files and inspect running processes, ports, and logs. No writes.
Full-power session
All tools available. Use only when you need the full surface and are actively watching.
How Scope Filtering Works
Scope filtering happens at two points:- Token issuance — the
/tokenendpoint encodes the granted scopes into the access token record. Scopes not inDEFAULT_OAUTH_SCOPES(or not explicitly requested) are never granted. - Tool dispatch — each tool checks whether the token’s granted scopes include the required scope before executing. A tool call with a missing scope returns an error immediately without touching the filesystem, shell, or browser.
Scopes are not the only gate. Policy modes independently cap which operations are permitted even within a granted scope. Both must permit an operation for it to succeed. See Policy Modes.