Skip to content

docs: add READ-ONLY caution to MCP Scripts reference #20600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Mar 11, 2026
Merged

docs: add READ-ONLY caution to MCP Scripts reference #20600

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d3a9f38
Initial plan
Copilot Mar 11, 2026
d130d3f
docs: add prominent READ-ONLY caution to mcp-scripts documentation
Copilot Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/src/content/docs/reference/mcp-scripts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,16 @@ sidebar:

The [`mcp-scripts:`](/gh-aw/reference/glossary/#mcp-scripts) element allows you to define custom [MCP](/gh-aw/reference/glossary/#mcp-model-context-protocol) (Model Context Protocol) tools directly in your workflow [frontmatter](/gh-aw/reference/glossary/#frontmatter) using JavaScript, shell scripts, or Python. These tools are generated at runtime and run as an HTTP MCP server **on the GitHub Actions runner, outside the agent container**. The agent reaches the server via `host.docker.internal`, keeping tool execution isolated from the AI sandbox while still providing controlled secret access.

> [!CAUTION]
> **MCP Scripts run outside the agent sandbox and must only implement READ-ONLY operations.**
Copy link

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency with the rest of the docs, consider using “read-only” (sentence case) instead of “READ-ONLY” in prose (e.g., docs/src/content/docs/guides/getting-started-mcp.md:106). Keeping “READ-ONLY” for diagrams/labels is fine, but in running text it reads like shouting.

This issue also appears on line 350 of the same file.

Suggested change
> **MCP Scripts run outside the agent sandbox and must only implement READ-ONLY operations.**
> **MCP Scripts run outside the agent sandbox and must only implement read-only operations.**

Copilot uses AI. Check for mistakes.
>
> Because MCP Scripts execute directly on the GitHub Actions runner host — not inside the isolated agent container — they can access the runner's file system, network, and environment without the safety constraints of the sandbox. Implementing **write operations** (creating files, pushing commits, calling mutating APIs, etc.) in MCP Scripts bypasses the audit trail and approval gates that protect your repository.
>
> - ✅ **Use MCP Scripts for**: reading data, querying APIs, fetching information, performing calculations.
> - ❌ **Do not use MCP Scripts for**: writing files, creating issues/PRs, modifying repository content, or any other mutating action.
Comment on lines +13 to +16
Copy link

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The “Do not use MCP Scripts for: writing files …” guidance is ambiguous given this page later documents that large outputs are saved to files automatically. Consider clarifying the prohibition as “writing/modifying repository content or making external state changes” (and, if acceptable, distinguish temporary local scratch files from mutating repo/API operations).

This issue also appears on line 13 of the same file.

Suggested change
> Because MCP Scripts execute directly on the GitHub Actions runner host — not inside the isolated agent container — they can access the runner's file system, network, and environment without the safety constraints of the sandbox. Implementing **write operations** (creating files, pushing commits, calling mutating APIs, etc.) in MCP Scripts bypasses the audit trail and approval gates that protect your repository.
>
> - ✅ **Use MCP Scripts for**: reading data, querying APIs, fetching information, performing calculations.
> - ❌ **Do not use MCP Scripts for**: writing files, creating issues/PRs, modifying repository content, or any other mutating action.
> Because MCP Scripts execute directly on the GitHub Actions runner host — not inside the isolated agent container — they can access the runner's file system, network, and environment without the safety constraints of the sandbox. Implementing operations that **modify repository content or make external state changes** (for example, writing or deleting tracked files, pushing commits, calling mutating APIs, or changing infrastructure) in MCP Scripts bypasses the audit trail and approval gates that protect your repository. Temporary local scratch files or automatically generated large-output files that stay within the runner workspace and are not committed are acceptable, as long as they are not used to perform mutating actions.
>
> - ✅ **Use MCP Scripts for**: reading data, querying APIs, fetching information, performing calculations.
> - ❌ **Do not use MCP Scripts for**: modifying repository content or persisting changes outside the sandbox (for example, committing or deleting files, creating issues/PRs, or calling mutating APIs), or any other external side-effecting action.

Copilot uses AI. Check for mistakes.
>
> For write operations, use [Safe Output Jobs](/gh-aw/reference/safe-outputs/) or [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/) instead. These run in a controlled, auditable step that is separate from the AI agent's execution.
Copy link

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Safe Output Jobs run as separate permission-controlled jobs, not a “step”. Suggest updating wording to “job”/“post-processing job” for accuracy (e.g., consistent with docs/src/content/docs/guides/getting-started-mcp.md:106).

Suggested change
> For write operations, use [Safe Output Jobs](/gh-aw/reference/safe-outputs/) or [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/) instead. These run in a controlled, auditable step that is separate from the AI agent's execution.
> For write operations, use [Safe Output Jobs](/gh-aw/reference/safe-outputs/) or [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/) instead. These run in a controlled, auditable post-processing job that is separate from the AI agent's execution.

Copilot uses AI. Check for mistakes.

## Quick Start

```yaml wrap
Expand Down Expand Up @@ -336,6 +346,9 @@ Analyze provided text using the `analyze-text` tool and create a discussion with

MCP Scripts tools run on the GitHub Actions **runner host** — outside the agent container — so they can access the runner's file system and environment but are isolated from the AI's own execution environment. Tools also provide secret isolation (only specified env vars are forwarded), process isolation (separate execution), and output sanitization (large outputs saved to files). Only predefined tools are available to agents.

> [!CAUTION]
> Because MCP Scripts execute outside the sandbox, **only implement READ-ONLY tools**. Write operations (file writes, API mutations, repository changes) must be handled through [Safe Output Jobs](/gh-aw/reference/safe-outputs/) or [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/), which provide proper audit trails and approval gates.

## Comparison with Other Options

| Feature | MCP Scripts | Custom MCP Servers | Bash Tool |
Expand Down
Loading