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 shell tool provides direct command execution through the system shell (PowerShell on Windows). It is the highest-risk single tool in the set and should be granted only when no dedicated MCP tool covers the required action. Before reaching for shell, check whether a purpose-built tool — file operations, git_* tools, start_process, tail_log, search, or delete/move/copy — already covers your use case. The shell is the escape hatch, not the default.
The shell tool runs with the full permissions of the Windows account running the MCP server. This is RCE-level access. A compromised or misbehaving session can read, write, and delete any file the account can touch, make outbound network calls, and launch further processes. Grant the mcp:shell scope only when you need it and understand this risk.
| Attribute | Value |
|---|
| Required scope | mcp:shell |
| Policy mode | operate |
| Risk tags | rce, process, network |
| Audit quality | coarse |
| On Windows | Executes via PowerShell |
Command policy
The shell tool is governed by the GPT_FS_MCP_SHELL_POLICY environment variable. Three values are accepted:
| Policy value | Behavior |
|---|
disabled | All shell calls are rejected immediately, regardless of scope. |
workspace_guarded | Path hints extracted from the command and expectedTouchedPaths are checked against workspace profile roots. |
full | No workspace path restriction is applied. The command runs wherever cwd points. |
Even with workspace_guarded, the shell tool is not a sandbox. It only checks that the path tokens found in the command string resolve within your allowed workspace roots. It cannot prevent side-effects that don’t involve explicit path references, such as network calls, registry writes, or spawning processes that act on other parts of the system.
What workspace_guarded checks
When policy is workspace_guarded, the server:
- Extracts path-like tokens from the command string (quoted strings, absolute paths,
./relative paths, and bare sensitive filenames such as .env).
- Adds any paths listed in
expectedTouchedPaths, resolved relative to cwd.
- Calls
assertPathAllowed on each resolved absolute path against your configured workspace profile roots.
- Also requires that
expectedTouchedPaths be non-empty for commands that look mutative (contain Set-Content, Out-File, rm, Remove-Item, > redirects, etc.).
If any path falls outside an allowed workspace root, the call is rejected before the command runs.
Parameters
| Parameter | Type | Required | Description |
|---|
command | string | ✅ | The command to execute. On Windows this is passed to PowerShell. |
cwd | string | ✅ | Required working directory for the command. Resolved and checked against workspace policy. |
purpose | string | ✅ | Short human-readable description of why this command is being run. Included in the audit journal. |
dedicatedToolBypassReason | string | ✅ | Explanation of why no dedicated MCP tool is sufficient. Logged for audit purposes. |
expectedTouchedPaths | string[] | ❌ | Paths the command is expected to read or write. Required for mutative commands under workspace_guarded. |
timeoutMs | number | ❌ | Per-call timeout in milliseconds. Capped at 600,000 ms. Defaults to GPT_FS_MCP_SHELL_TIMEOUT_MS. |
Timeout
The default timeout is controlled by GPT_FS_MCP_SHELL_TIMEOUT_MS (default: 120000 ms / 2 minutes). You can override it per call via the timeoutMs parameter up to a hard cap of 600,000 ms (10 minutes).
Response fields
| Field | Description |
|---|
stdout | Standard output from the command (may be truncated). |
stderr | Standard error output (may be truncated). |
code | Exit code, or null if the process was signalled or timed out. |
signal | Signal name if the process was killed by a signal, otherwise null. |
timedOut | true if the command exceeded timeoutMs. |
outputLimitExceeded | true if combined output exceeded the server’s max output bytes limit. |
durationMs | Wall-clock time the command took in milliseconds. |
auditQuality | Always "coarse" — shell output is not file-granular. |
effectivePathHints | Absolute paths extracted from the command, used for workspace path checks. |
warnings | Path-related warnings (outside workspace, secret file references, etc.). |
Example: running a build
{
"tool": "shell",
"arguments": {
"command": "npm run build",
"cwd": "C:\\Users\\dev\\projects\\my-app",
"purpose": "Build the TypeScript project before deployment",
"dedicatedToolBypassReason": "No dedicated build tool; project uses a custom npm script",
"expectedTouchedPaths": ["dist"],
"timeoutMs": 120000
}
}
"code": 0 and the combined stdout/stderr from the build process.
shell is synchronous — it blocks until the command exits or times out, then returns the output. Use shell for:
- Tests and one-shot builds
- Quick CLI operations (e.g.
git status, npm install)
- Any command expected to complete within the timeout
For long-running background processes — dev servers, file watchers, queue workers — use start_process instead. start_process captures stdout/stderr to managed log files, survives the MCP request boundary, and can be stopped cleanly with stop_process.
If a shell command produces a large log output that you need to monitor over time, start it with start_process and stream its output with tail_log.
See also
- Command Policies — full reference for
GPT_FS_MCP_SHELL_POLICY and workspace_guarded path checking
- Security Scopes — how to enable and restrict the
mcp:shell scope