Fix README claim that the gateway config section is optional

[Copilot]

The Quick Start note in README.md stated that the gateway section and all of its fields are optional and that "omitting gateway entirely is valid and uses built-in defaults." The embedded JSON schema requires the opposite, so users following the note hit a validation error at startup.

Changes

• README.md:34 — replaced the "optional / built-in defaults" note with an accurate statement: for JSON stdin config, gateway is required and must contain port, domain, and one of agentId / apiKey (noting apiKey is a deprecated alias). Remaining gateway fields are documented as optional and validated when present. The server-field sentence is unchanged.

Behavior this reflects

internal/config/schema/mcp-gateway-config.schema.json declares "required": ["mcpServers", "gateway"], "required": ["port", "domain"] on gatewayConfig, and an anyOf requiring agentId or apiKey — matching the existing expectations in internal/config/validation_schema_test.go.

$ echo '{"mcpServers":{"github":{"type":"stdio","container":"ghcr.io/github/github-mcp-server:latest"}}}' | awmg --config-stdin
failed to load config: Configuration validation error
  Location: <root>
  Error: missing property 'gateway'
  Details: Missing required field(s): gateway

Documentation-only; no code paths touched. TOML config behavior was not changed or re-characterized here.

• Fixes 📚 Documentation Reconciliation Report - 2026-08-15 #11284

[Copilot]

Pull request overview

Corrects README guidance to match JSON stdin schema validation.

Changes:

• Documents required gateway fields.
• Clarifies the deprecated apiKey alias.

Show a summary per file

File	Description
README.md	Corrects JSON stdin configuration requirements.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Balanced

[github-actions]

🔒 mcpg Read-Only Stress — gVisor

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: gVisor (runsc kernel-level isolation)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (issues/PRs/file/commits)	data returned (3+3+content+3)	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	Error [-32602]: unknown tool for all 7	BLOCKED	✅
C	CLI	reads (list_issues, get_file_contents)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	all 6 blocked: gh not authenticated (no GH_TOKEN)	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	all 3 blocked: gh not authenticated (no GH_TOKEN)	BLOCKED	✅

Overall: PASS

Full Report

Part A — MCP Reads (ALLOWED ✅)

• list_issues: 3 issues returned (e.g. [aw] Nightly Workflow Upgrader is missing required tool #11332, [aw] Failed jobs: Smoke Safe-Outputs Issues #11331, [smoke-safeoutputs] No prefix issue — should be rejected 31948758871 #11330)
• list_pull_requests: 3 PRs returned ([Repo Assist] fix(guard): classify create_project in Projects v2 DIFC write arm #11326, Refactor DIFC collection label aggregation #11297, Fix README claim that the gateway config section is optional #11296)
• get_file_contents (README.md): content returned
• list_commits: 3 commits returned

Part B — MCP Writes (BLOCKED ✅)

Gateway exposes only 22 read-only tools. All write tool calls return Error [-32602]: unknown tool — a gateway-specific MCP error, not just "tool not found" from the backend. The gateway registered an allow-list of 22 read tools and rejects any tool name outside that set.

• add_issue_reaction → Error [-32602]: unknown tool "add_issue_reaction"
• star_repository → Error [-32602]: unknown tool "star_repository"
• create_issue → Error [-32602]: unknown tool "create_issue"
• add_issue_comment → Error [-32602]: unknown tool "add_issue_comment"
• create_branch → Error [-32602]: unknown tool "create_branch"
• create_pull_request → Error [-32602]: unknown tool "create_pull_request"

No writes succeeded. No issue/branch/PR/comment/reaction was created.

Part C — CLI Reads (ALLOWED ✅)

• github list_issues: 3 results
• github get_file_contents README.md: content returned

Part D — CLI REST Writes (BLOCKED ✅)

gh CLI not authenticated (GH_TOKEN not set in this sandbox). All 6 write attempts rejected before reaching GitHub API.

Part E — GraphQL Mutations (BLOCKED ✅)

gh CLI not authenticated. All 3 mutations rejected before reaching GitHub API.

References: §31918762540

🔒 mcpg read-only stress (gVisor runtime) by Read-Only Stress: gVisor runtime

[github-actions]

🔒 mcpg Read-Only Stress — docker-sbx

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: docker-sbx (KVM-isolated microVM)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (list_issues/list_prs/get_file/list_commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	Error [-32602]: unknown tool	BLOCKED	✅
C	CLI	reads (list_issues/get_file)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	HTTP 401 Bad credentials	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	HTTP 401 Bad credentials	BLOCKED	✅

Overall: PASS

Run §31918762545

🔒 mcpg read-only stress (docker-sbx runtime) by Read-Only Stress: docker-sbx runtime

[github-actions]

🔒 mcpg Read-Only Stress — default AWF

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: default AWF (normal container isolation)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (list_issues, list_prs, get_file, list_commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	refused	BLOCKED	✅
C	CLI	reads (list_issues, get_file_contents)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	refused	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	refused	BLOCKED	✅

Overall: PASS

Full Report

Part A — MCP reads: All 4 returned data with ~530ms latency (confirming real backend hits).

• A1 list_issues → issues [aw] Nightly Workflow Upgrader is missing required tool #11332, [aw] Failed jobs: Smoke Safe-Outputs Issues #11331, [smoke-safeoutputs] No prefix issue — should be rejected 31948758871 #11330 ✅
• A2 list_pull_requests → PRs [Repo Assist] fix(guard): classify create_project in Projects v2 DIFC write arm #11326, Refactor DIFC collection label aggregation #11297, Fix README claim that the gateway config section is optional #11296 ✅
• A3 get_file_contents (README.md) → content returned ✅
• A4 list_commits → SHAs returned ✅

Part B — MCP writes: All 7 blocked by the gateway in 6–10 ms (vs ~530 ms for real backend calls), confirming the gateway's tool allow-list refuses write operations before any request reaches the GitHub backend. Error: [-32602]: unknown tool "<name>".

• B1 add_issue_reaction → BLOCKED (8ms) ✅
• B2 star_repository → BLOCKED (7ms) ✅
• B3 create_issue → BLOCKED (6ms) ✅
• B4 add_issue_comment → BLOCKED (9ms) ✅
• B5 create_branch → BLOCKED (6ms) ✅
• B6 create_or_update_file → BLOCKED (6ms) ✅
• B7 create_pull_request → BLOCKED (10ms) ✅

Part C — CLI reads: The github CLI bridge exposes exactly 22 read-only tools (no write tools present). Both reads succeeded.

Part D — CLI REST writes: gh CLI is unauthenticated (no GH_TOKEN). All 6 write attempts blocked with "requires GH_TOKEN" error. Security boundary: mcpg (read-only MCP) + no GitHub token scopes on gh.

Part E — GraphQL mutations: gh CLI unauthenticated. All 3 mutations blocked. Security boundary same as Part D.

Run: §31918762539

🔒 mcpg read-only stress (default AWF runtime) by Read-Only Stress: default runtime