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.
Process tools manage background processes, port visibility, and log streams on the local Windows machine. All seven tools require the mcp:process scope. The group divides naturally into read-only observation tools (process_list, port_list, tail_log), a diagnostic polling tool (wait_for_port), and mutative operate tools (start_process, stop_process, process_kill). The operate tools are additionally gated by the operate policy mode, and start_process is governed by GPT_FS_MCP_PROCESS_POLICY.
1. process_list
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | observe |
| Risk tags | process-disclosure |
Win32_Process via PowerShell. On Linux/macOS, runs ps -eo.
Parameters
| Parameter | Type | Default | Description |
|---|
includeCommandLine | boolean | false | Whether to include the full redacted command line for each process. |
maxProcesses | number | 500 | Maximum number of processes to return (max 2000). Truncation is indicated by truncated: true. |
processes (array of { pid, name, parentPid?, commandLine? }) and truncated boolean.
2. port_list
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | observe |
| Risk tags | network-disclosure |
netstat. Reveals which ports are open and which PIDs own them. This information may disclose internal service topology.
Parameters
| Parameter | Type | Default | Description |
|---|
protocol | "tcp" | "udp" | "all" | "all" | Filter output by protocol family. |
ports (array of { localAddress, localPort, pid, protocol, remoteAddress?, remotePort?, state? }).
3. tail_log
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | observe |
| Risk tags | log-read |
start_process. Prefer this over shell Get-Content -Tail, tail, or polling. You can address a log either by managed processId (which bypasses path checks since the server owns that file) or by an explicit path.
Parameters
| Parameter | Type | Default | Description |
|---|
processId | string (UUID) | — | ID returned by start_process. Use this to tail stdout/stderr without a file path. |
path | string | — | Log file path to tail. Required if processId is not provided. |
cwd | string | — | Base directory for resolving a relative path. |
stream | "stdout" | "stderr" | "stdout" | Which stream to read when using processId. |
maxBytes | number | 100000 | Maximum bytes to read from the tail (max 1,000,000). |
content (string), bytesRead, path (resolved absolute path), truncated.
4. wait_for_port
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | diagnose |
| Risk tags | network-probe |
host:port until it becomes reachable or the timeout elapses. By default only loopback addresses (localhost, 127.0.0.1, ::1) are allowed; pass allowRemote: true to reach non-loopback hosts.
Parameters
| Parameter | Type | Default | Description |
|---|
port | number | (required) | TCP port number to probe (1–65535). |
host | string | "127.0.0.1" | Hostname or IP to connect to. |
allowRemote | boolean | false | Allow non-loopback hosts. Required for anything other than localhost. |
intervalMs | number | 250 | Polling interval in milliseconds (max 10,000). |
timeoutMs | number | 30000 | Total wait timeout in milliseconds (max 120,000). |
reachable (boolean), host, port, elapsedMs. Returns isError: true if the port was not reached before timeout.
5. start_process
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | operate |
| Risk tags | rce, process, long-running |
| Policy env var | GPT_FS_MCP_PROCESS_POLICY |
shell Start-Process, npm start, npm run dev, Vite, or any command that should keep running after the MCP request completes. Stdout and stderr are captured to managed log files that survive the MCP request boundary. The server tracks up to 100 concurrent managed processes.
This tool defaults to dryRun: true. A dry run returns the resolved command, path hints, and any warnings without actually launching anything. Set dryRun: false and confirm: true to execute.
Command policy
Governed by GPT_FS_MCP_PROCESS_POLICY:
| Policy value | Behavior |
|---|
disabled | All start_process calls are rejected. |
workspace_guarded | Path tokens in the command and cwd are verified against workspace profile roots before launching. |
full | No workspace path restriction; the process runs wherever cwd points. |
| Parameter | Type | Default | Description |
|---|
command | string | (required) | The command to run as a background process. |
cwd | string | (required) | Working directory for the process. Resolved and checked against workspace policy. |
dryRun | boolean | true | When true, validates and returns a preview without launching. |
confirm | boolean | false | Must be true when dryRun is false. |
maxLogBytes | number | 1000000 | Per-stream log cap in bytes (max 50,000,000). Logs are truncated at this limit. |
processId (UUID), pid, cwd, commandRedacted, stdoutPath, stderrPath, maxLogBytes, effectivePathHints, warnings.
Use the returned processId with tail_log, stop_process, and to identify the process in process_list output.
6. stop_process
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | operate |
| Risk tags | process-kill |
start_process. On Windows, uses taskkill /PID … /T /F; on Linux/macOS, sends SIGTERM. Like start_process, defaults to dryRun: true.
Parameters
| Parameter | Type | Default | Description |
|---|
processId | string (UUID) | (required) | The processId returned by start_process. |
dryRun | boolean | true | Preview without stopping. |
confirm | boolean | false | Must be true when dryRun is false. |
stopped, exited, pid, processId, code, stdout, stderr.
7. process_kill
| Attribute | Value |
|---|
| Required scope | mcp:process |
| Policy mode | operate |
| Risk tags | process-kill |
taskkill /PID … /T /F (tree kill by default). Defaults to dryRun: true.
process_kill is irreversible. Killing the wrong PID can terminate user applications, editors, databases, or background services with no recovery path for unsaved state. Always perform a dry run first and verify name/commandLine in the response before setting confirm: true.
| Parameter | Type | Default | Description |
|---|
pid | number | (required) | OS process ID to kill. |
dryRun | boolean | true | Preview the kill target without executing. |
confirm | boolean | false | Must be true when dryRun is false. |
tree | boolean | true | Kill the entire process tree (child processes included). |
expectedName | string | — | Guard: reject if the process name doesn’t match. |
expectedCommandSubstring | string | — | Guard: reject if the command line doesn’t include this substring. |
allowCritical | boolean | false | Allow killing processes flagged as critical (e.g. cloudflared). Requires explicit opt-in. |
killed, pid, name, commandLine, code, stdout, stderr.
Practical workflow: start a dev server
A common pattern is to start a dev server, wait for its port to become available, then tail its log to verify startup.
// Step 1 — dry run to preview
{
"tool": "start_process",
"arguments": {
"command": "npm run dev",
"cwd": "C:\\Users\\dev\\projects\\my-app",
"dryRun": true
}
}
// Step 2 — confirm and launch
{
"tool": "start_process",
"arguments": {
"command": "npm run dev",
"cwd": "C:\\Users\\dev\\projects\\my-app",
"dryRun": false,
"confirm": true
}
}
// Step 3 — wait for the server to be ready
{
"tool": "wait_for_port",
"arguments": {
"port": 5173,
"host": "127.0.0.1",
"timeoutMs": 30000
}
}
// Step 4 — tail the stdout log
{
"tool": "tail_log",
"arguments": {
"processId": "<uuid from step 2>",
"stream": "stdout",
"maxBytes": 50000
}
}
See also
- Command Policies — reference for
GPT_FS_MCP_PROCESS_POLICY and workspace path enforcement