docs: add READ-ONLY caution to MCP Scripts reference

[Copilot]

MCP Scripts run on the GitHub Actions runner host — outside the agent sandbox — making write operations a security concern with no audit trail. The docs lacked any warning about this constraint.

Changes

• Top-of-page [!CAUTION] block — added immediately after the intro paragraph (before Quick Start) with explicit do/don't guidance and a redirect to Safe Output Jobs for write operations
• Security Considerations [!CAUTION] — concise reinforcement for users who skip to that section

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build tion instructio (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Add a proéminent caution not in the mcp-scripts documentation to only implement READ ONLY scripts! MCP-scripts escapes the sandbox and should NOT be used to create "write" tools. Use safe jobs instead.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[Copilot]

Pull request overview

Adds prominent documentation warnings that MCP Scripts run on the GitHub Actions runner host (outside the agent sandbox) and should be used for read-only operations, directing users to Safe Output Jobs for any mutating actions.

Changes:

• Added a top-of-page [!CAUTION] block with explicit read-only guidance and pointers to Safe Output Jobs / Custom Safe Output Jobs.
• Added a reinforcing [!CAUTION] in the “Security Considerations” section.

Comments suppressed due to low confidence (2)

docs/src/content/docs/reference/mcp-scripts.md:350

• For consistency with the rest of the docs, consider using “read-only” (sentence case) instead of “READ-ONLY” here as well (see docs/src/content/docs/guides/getting-started-mcp.md:106).

> 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.

docs/src/content/docs/reference/mcp-scripts.md:13

• “bypasses the audit trail” reads as though MCP Scripts have no logging/traceability at all. Since MCP Scripts executions still appear in GitHub Actions logs/step summaries, consider tightening this to say they bypass the Safe Output Jobs audit/approval gates (or that they lack the structured, reviewable audit trail that safe outputs provide).

> 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.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

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]

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]

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.**