Clarify MCP localhost rewrite, transport semantics, and reachability under network isolation

[Copilot]

The MCP server spec had ambiguous behavior around network isolation: localhost HTTP endpoints are rewritten internally, but binding constraints and transport semantics were not documented. This created avoidable failures when workflows started local servers on loopback while gateway traffic resolved via host.docker.internal.

• Spec: localhost rewrite behavior

  • Added explicit rule that with sandbox.agent.sudo: false, loopback HTTP MCP URLs (localhost, 127.0.0.1, ::1) are rewritten to host.docker.internal.
  • Clarified this is required because the MCP gateway runs in a container and cannot reach host loopback directly.

• Spec: host-side server binding requirements

  • Documented that host-started HTTP MCP servers must bind to 0.0.0.0 (or other non-loopback interface) when isolation is enabled.
  • Added guidance that compiler/lint should warn on loopback URL + loopback bind combinations (e.g. --host 127.0.0.1, --bind ::1).

• Spec: transport model reconciliation

  • Clarified the two-layer model:
    • frontmatter authoring (mcp-servers with command/args or url)
    • compiler-generated MCP gateway runtime config.
  • Explicitly states frontmatter stdio command/args compiles into gateway stdio/stdin process configuration.

• Spec: network reachability matrix

  • Added a matrix covering HTTP localhost, host.docker.internal, external URLs, and stdio (container and command/args) across isolation ON/OFF.

mcp-servers:
  local-http:
    url: "http://localhost:8081/mcp"   # isolation ON => rewritten to host.docker.internal
  local-stdio:
    command: "uvx"
    args: ["my-mcp-server"]

sandbox:
  agent:
    sudo: false

[Copilot]

Pull request overview

This PR updates the GitHub Agentic Workflows documentation to remove ambiguity around MCP gateway transport semantics and network reachability when network isolation is enabled, especially for host-local HTTP MCP servers.

Changes:

• Documents the two-layer MCP server configuration model (frontmatter authoring vs compiler-generated gateway runtime config).
• Specifies localhost rewrite behavior for HTTP MCP URLs under network isolation and explains why it’s necessary.
• Adds host-side binding requirements and a reachability matrix covering isolation ON/OFF across MCP transport types.

Show a summary per file

File	Description
.github/aw/github-agentic-workflows.md	Adds a new “MCP Transport and Reachability” section clarifying localhost rewrite, binding requirements, and a reachability matrix under network isolation.

Review details

Tip

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

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Low

[github-actions]

✅ Copilot review passed with no inline comments.

@copilot Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

[github-actions]

🌑 The shadows whisper... Smoke Codex failed. The oracle requires further meditation...

[github-actions]

✅ Smoke Copilot BYOK AOAI (Entra) completed. Copilot AOAI BYOK (Entra) mode operational. 🔓

[github-actions]

✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓

[github-actions]

✅ Smoke Claude passed

[github-actions]

✅ Smoke Copilot BYOK AOAI (api-key) completed. Copilot AOAI BYOK (api-key) mode operational. 🔓

[github-actions]

🔌 Smoke Services — All services reachable! ✅

[github-actions]

🚀 Security Guard has started processing this pull request

[github-actions]

Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded.

[github-actions]

✅ Build Test Suite completed successfully!

[github-actions]

✅ Smoke Gemini completed. All facets verified. 💎

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

[github-actions]

✅ Contribution Check completed successfully!

PR #6005 follows the applicable CONTRIBUTING.md guidelines based on the pre-fetched context; no review comment needed.

[github-actions]

📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅

[github-actions]

🔑 Smoke Copilot PAT PAT auth validated. All systems operational. ✅

[github-actions]

Smoke Test Results

• Redis PING: ❌ Network unreachable
• PostgreSQL pg_isready: ❌ No response
• PostgreSQL SELECT 1: ❌ Network unreachable

Overall: FAIL — host.docker.internal is not reachable from this runner. Service containers may not be running or the host alias is not configured.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🔌 Service connectivity validated by Smoke Services
_{Add label ready-for-aw to run again}

[github-actions]

✅ Copilot BYOK Smoke Test: PASS

Test	Result
GitHub MCP (PR list)	✅
github.com HTTP 200	✅
File write/read	✅
BYOK inference	✅

Mode: Direct BYOK (COPILOT_PROVIDER_API_KEY) → api-proxy → api.githubcopilot.com
Status: All systems operational 🔓

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🔑 BYOK report filed by Smoke Copilot BYOK
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: Claude Engine Validation

Check	Result
API status	✅ PASS
gh check	✅ PASS
File status	✅ PASS

Overall result: PASS

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by Smoke Claude for #6005 · 55.2 AIC · ⊞ 5.8K · ◷
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test Results

• GitHub MCP Testing: ❌ (Tool missing)
• GitHub.com Connectivity: ❌ (Status 000, Exit 7)
• File Writing Testing: ✅ (Verified)
• Bash Tool Testing: ❌ (Restricted)

Overall status: FAIL

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• localhost

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "localhost"

See Network Configuration for more information.

💎 Faceted by Smoke Gemini
_{Add label ready-for-aw to run again}

[github-actions]

🔬 Smoke Test Results

Test	Status
GitHub MCP Connectivity	✅
GitHub.com HTTP	✅ (200)
File Write/Read	⚠️ (template vars unexpanded in workflow)

Overall: PASS (core connectivity verified)

@lpcox

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

📰 BREAKING: Report filed by Smoke Copilot
_{Add label ready-for-aw to run again}

[github-actions]

@lpcox

• GitHub MCP test: ✅
• GitHub.com connectivity: ✅
• File write/read test: ❌
• BYOK inference: ✅
  Running in direct BYOK mode (AWF_AUTH_TYPE=github-oidc + AWF_AUTH_AZURE_* + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw) authenticated via Microsoft Entra
  Overall: FAIL

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🪪 BYOK (AOAI Entra) report filed by Smoke Copilot BYOK AOAI (Entra)
_{Add label ready-for-aw to run again}

[github-actions]

🔥 Smoke Test: PAT Auth — PASS

Test	Result
GitHub MCP (list merged PRs)	✅ PR #6005 found
GitHub.com connectivity	✅ HTTP 200
File write/read	✅ /tmp/gh-aw/agent/smoke-test-copilot-pat-28913841426.txt

Auth mode: PAT (COPILOT_GITHUB_TOKEN)
Author: @Copilot · Assignees: @lpcox @Copilot

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🔑 PAT report filed by Smoke Copilot PAT
_{Add label ready-for-aw to run again}

[github-actions]

🔬 Smoke Test: API Proxy OpenTelemetry Tracing

Scenario	Result	Notes
1. Module Loading	✅	otel.js loads OK; exports: startRequestSpan, setTokenAttributes, setBudgetAttributes, endSpan, endSpanError, shutdown, isEnabled + internals
2. Test Suite	✅	59 tests passed (otel.test.js: 39, otel-fanout.test.js: 20)
3. Env Var Forwarding	✅	api-proxy-env-config.ts forwards GH_AW_OTLP_ENDPOINTS, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, GITHUB_AW_OTEL_TRACE_ID, GITHUB_AW_OTEL_PARENT_SPAN_ID, OTEL_SERVICE_NAME
4. Token Tracker Integration	✅	onUsage callback present in token-tracker-http.js (line 324); proxy-guards.js wires OTEL with graceful degradation (no-op fallback when module absent)
5. OTEL Diagnostics	✅	No OTLP endpoint configured → spans fall back to FileSpanExporter at /var/log/api-proxy/otel.jsonl (local fallback mode, as designed)

All 5 scenarios pass. OTEL tracing integration is complete and functioning correctly.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

📡 OTel tracing validated by Smoke OTel Tracing
_{Add label ready-for-aw to run again}

[github-actions]

Chroot Version Comparison Results

Runtime	Host Version	Chroot Version	Match?
Python	Python 3.12.13	Python 3.12.3	❌
Node.js	v24.18.0	v22.23.1	❌
Go	go1.22.12	go1.22.12	✅

Result: Not all tests passed — Python and Node.js versions differ between host and chroot. The smoke-chroot label was not applied.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Tested by Smoke Chroot
_{Add label ready-for-aw to run again}

[github-actions]

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	passed	✅ PASS
Go	env	✅	passed	✅ PASS
Go	uuid	✅	passed	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	passed	✅ PASS
Node.js	execa	✅	passed	✅ PASS
Node.js	p-limit	✅	passed	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — ✅ PASS

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by Build Test Suite for #6005 · 47.5 AIC · ⊞ 6.9K · ◷
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🔑 BYOK (AOAI api-key) report filed by Smoke Copilot BYOK AOAI (api-key)
_{Add label ready-for-aw to run again}