powershell-mcp

Overview Schema Source Related Servers Discussions Admin

run_program

Execute native executables directly without a shell in a hidden process, capturing clean stdout, stderr, and exit codes from an argument array.

Instructions

Run a native executable DIRECTLY (no shell) in a hidden process and capture clean stdout/stderr + exit code. Use this for console programs like gh, git, docker, node, python, etc. -- direct execution captures their stdout/stderr without PowerShell pipeline semantics. Historical hidden-shell native stdout loss is executable/environment-specific; it is not universal. Provide the program and an args array (no shell quoting needed).

Input Schema

Name	Required	Description
`cwd`	No	Working directory.
`args`	No	Arguments as an array; each element is passed verbatim (no shell quoting).
`tail`	No	Keep last bytes rather than first; incomplete UTF-8 boundary scalars are omitted.
`stdin`	No	UTF-8 stdin, max 1 MiB bytes. Empty string still opens stdin and sends EOF; no stdin in argv, environment or logs.
`program`	Yes	Executable name on PATH or a full path, e.g. 'git' or 'C:\Program Files\GitHub CLI\gh.exe'.
`logOutput`	No	Opt in to private file-backed raw output logs; may include secrets emitted by command.
`timeoutMs`	No	Hard timeout in ms (default 60000).
`logQuotaBytes`	No	Combined stdout/stderr quota (default 8 MiB); incomplete beyond quota.
`maxOutputBytes`	No	Raw UTF-8 bytes per stream (default 1 MiB).

Output Schema

Name	Required	Description	Default
`log`	No
`detail`	Yes
`stderr`	Yes
`stdout`	Yes
`target`	Yes
`exitCode`	Yes
`timedOut`	Yes
`transport`	Yes
`durationMs`	Yes
`truncation`	Yes
`executionId`	Yes
`errorRecords`	No
`schemaVersion`	Yes
`terminationStatus`	Yes
`terminationCertainty`	Yes
`errorRecordsTruncated`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.7.0Oct 24, 2026

addedInput schema / properties / logOutput

Added value: +{
+  "description": "Opt in to private file-backed raw output logs; may include secrets emitted by command.",
+  "type": "boolean"
+}

addedInput schema / properties / logQuotaBytes

Added value: +{
+  "description": "Combined stdout/stderr quota (default 8 MiB); incomplete beyond quota.",
+  "exclusiveMinimum": 0,
+  "maximum": 8388608,
+  "type": "integer"
+}

addedInput schema / properties / maxOutputBytes

Added value: +{
+  "description": "Raw UTF-8 bytes per stream (default 1 MiB).",
+  "exclusiveMinimum": 0,
+  "maximum": 8388608,
+  "type": "integer"
+}

addedInput schema / properties / stdin

Added value: +{
+  "description": "UTF-8 stdin, max 1 MiB bytes. Empty string still opens stdin and sends EOF; no stdin in argv, environment or logs.",
+  "maxLength": 1048576,
+  "type": "string"
+}

addedInput schema / properties / tail

Added value: +{
+  "description": "Keep last bytes rather than first; incomplete UTF-8 boundary scalars are omitted.",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "detail": {
+      "additionalProperties": false,
+      "properties": {
+        "bytes": {
+          "type": "number"
+        },
+        "cleanup": {
+          "enum": [
+            "not_needed",
+            "removed",
+            "failed",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "direction": {
+          "enum": [
+            "upload",
+            "download"
+          ],
+          "type": "string"
+        },
+        "error": {
+          "type": "string"
+        },
+        "finalized": {
+          "type": "boolean"
+        },
+        "localExitCode": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sha256": {
+          "type": "string"
+        },
+        "shell": {
+          "type": "string"
+        },
+        "signal": {
+          "type": "string"
+        },
+        "verification": {
+          "enum": [
+            "not_started",
+            "sha256_matched",
+            "failed"
+          ],
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "durationMs": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "errorRecords": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string"
+          },
+          "exceptionType": {
+            "type": "string"
+          },
+          "fullyQualifiedErrorId": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "category",
+          "fullyQualifiedErrorId",
+          "exceptionType",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "errorRecordsTruncated": {
+      "type": "boolean"
+    },
+    "executionId": {
+      "type": "string"
+    },
+    "exitCode": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "log": {
+      "additionalProperties": false,
+      "properties": {
+        "complete": {
+          "type": "boolean"
+        },
+        "expiresAt": {
+          "type": "string"
+        },
+        "handle": {
+          "type": "string"
+        },
+        "stderrBytes": {
+          "type": "number"
+        },
+        "stdoutBytes": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "handle",
+        "complete",
+        "stdoutBytes",
+        "stderrBytes",
+        "expiresAt"
+      ],
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 1,
+      "type": "number"
+    },
+    "stderr": {
+      "type": "string"
+    },
+    "stdout": {
+      "type": "string"
+    },
+    "target": {
+      "type": "string"
+    },
+    "terminationCertainty": {
+      "enum": [
+        "unknown",
+        "root_exited"
+      ],
+      "type": "string"
+    },
+    "terminationStatus": {
+      "enum": [
+        "completed",
+        "nonzero_exit",
+        "script_error",
+        "remote_error",
+        "timeout",
+        "cancelled",
+        "transport_error",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "timedOut": {
+      "type": "boolean"
+    },
+    "transport": {
+      "enum": [
+        "powershell",
+        "program",
+        "winrm",
+        "ssh",
+        "sftp"
+      ],
+      "type": "string"
+    },
+    "truncation": {
+      "additionalProperties": false,
+      "properties": {
+        "limitBytesPerStream": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "stderr": {
+          "additionalProperties": false,
+          "properties": {
+            "capturedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "observedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "omittedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "observedBytes",
+            "capturedBytes",
+            "omittedBytes",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        "stdout": {
+          "additionalProperties": false,
+          "properties": {
+            "capturedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "observedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "omittedBytes": {
+              "minimum": 0,
+              "type": "number"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "observedBytes",
+            "capturedBytes",
+            "omittedBytes",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "truncated",
+        "limitBytesPerStream"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "executionId",
+    "transport",
+    "target",
+    "stdout",
+    "stderr",
+    "exitCode",
+    "durationMs",
+    "timedOut",
+    "truncation",
+    "terminationStatus",
+    "terminationCertainty",
+    "detail"
+  ],
+  "type": "object"
+}

First observedv0.5.0Aug 6, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses direct (no-shell) execution, a hidden process, captured streams and exit code, and proactively addresses a known stdout-loss caveat as executable/environment-specific rather than universal. It does not mention synchronous/blocking behavior or privilege needs, which limits it below 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior and return capture, then usage, then the caveat. Every sentence is relevant, though the historical stdout-loss sentence is slightly dense and could be tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be explained, and the 9 parameters are fully documented in the schema. For an arbitrary-program execution tool with no annotations, it covers the essentials, though a brief note on blocking behavior or that it executes arbitrary code would complete the picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so timeout, quota, stdin, tail and logging semantics are already documented in the schema. The description only reinforces 'provide the program and an args array (no shell quoting needed)', adding marginal value over the structured fields, which is the baseline-3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a native executable DIRECTLY (no shell) in a hidden process') plus what it returns (stdout/stderr + exit code). It explicitly contrasts with PowerShell pipeline semantics, which is exactly how the sibling run_powershell differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this for console programs like gh, git, docker, node, python, etc.' gives concrete, actionable cases, and the note about avoiding PowerShell pipeline semantics routes the agent away from run_powershell. It stops short of naming run_powershell as the alternative, so the exclusion is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.