Repository navigation
Description
Problem
An agentic workflow (daily-team-status) hard-failed because an MCP server defined in the repo's .mcp.json failed to launch inside the gh-aw sandbox — even though the workflow never requested that server.
Failed run: https://github.com/RealPage/task-management/actions/runs/23258101607
Root Cause
The repo had a .mcp.json at the root configuring a SonarQube MCP server that launches via Docker. The coding agent auto-discovers .mcp.json and attempts to start all servers defined in it. Inside the gh-aw chroot sandbox:
- Docker is unavailable — the sandbox is a chroot jail, not a full Docker environment. The Docker socket is not mounted, so the
docker runcommand fails immediately. - The image is not pre-pulled — the
Download container imagesstep only pulls gh-aw infrastructure images, not project-specific MCP images. - Docker Hub is not on the firewall allowlist — even if Docker were available,
registry-1.docker.io/production.cloudflare.docker.comare not in--allow-domains, so image pulls would be blocked.
The failure happens at the Docker binary/socket level before any network call — confirmed by firewall logs showing 0 blocked requests and only 2 unique domains (api.anthropic.com, raw.githubusercontent.com).
Error
ERR_API: MCP server(s) failed to launch: sonarqube
This error annotation marks the entire job as failure, despite the agent completing successfully and producing all expected outputs.
Workaround
We removed .mcp.json from version control and added it to .gitignore (https://github.com/RealPage/task-management/pull/1129). Developers recreate it locally. This works but sacrifices the "just works on clone" experience for project-specific MCP servers.
Request
MCP server launch failures should not be fatal for servers that are not explicitly declared in the workflow's tools: frontmatter. Two possible approaches:
- Preferred: Make auto-discovered MCP servers (from
.mcp.json) non-fatal for agentic workflows that don't declare them intools:— treat them as best-effort - Alternative: Support an
optional: trueflag per MCP server in.mcp.json, so repos can mark servers that should not block workflows on failure
Impact
Any repo with a .mcp.json that includes servers requiring Docker, local secrets, or external connectivity will break all scheduled agentic workflows — even workflows that have no dependency on those servers.
Activity
pelikhan commentedon Mar 20, 2026
I cannot access this run. What agent are you using? We should not be loading any MPC automatically and we need to make sure to turn off this behavior.
pelikhan commentedon Apr 10, 2026
/scout do a deep research to determine if there are cli args to disable auto loading of .mcp.json
github-actions commentedon Apr 10, 2026
🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️
github-actions commentedon Apr 10, 2026
🔍 Scout Research Report
Triggered by
@pelikhanExecutive Summary
There are CLI arguments to disable auto-loading of
.mcp.jsonin Claude Code, but no gh-aw frontmatter option currently exists to control this at the workflow level. The key flag is--strict-mcp-config, which — when paired with--mcp-config '{}'— prevents Claude Code from auto-discovering any project or user MCP servers. However, this is a Claude Code CLI concern; gh-aw's own frontmatter does not expose a mechanism to skip loading a repo's.mcp.json.Click to expand detailed findings
Research Findings
--strict-mcp-config— The Primary FlagFrom the [official Claude Code CLI reference]((code.claude.com/redacted) and community documentation:
--strict-mcp-config: "Only use MCP servers from--mcp-config, ignoring all other MCP configurations." This explicitly prevents.mcp.jsonauto-discovery.--mcp-config <file|json>: Specifies a custom MCP config file or inline JSON string.To disable ALL MCP server loading:
claude --strict-mcp-config --mcp-config '{}'This combination passes an empty config and tells Claude Code to ignore any auto-discovered
.mcp.json.Known bug (anthropics/claude-code#14490):
--strict-mcp-configdoes not override thedisabledMcpServerslist in~/.claude.json, which can cause unexpected behavior in some configurations.CLAUDE_MCP_SKIP_WAIT=true— Non-Blocking ConnectionSetting this environment variable in non-interactive (
-p) mode skips waiting for MCP connections, bounding server startup to 5 seconds instead of blocking indefinitely. This does not prevent servers from loading, but prevents slow/failed servers from blocking the workflow.This is particularly relevant to this issue: it would reduce the blast radius of a Docker-based MCP server failing to connect, but wouldn't prevent the
ERR_API: MCP server(s) failed to launchfailure annotation.--no-mcp— Not Yet ImplementedFeature request anthropics/claude-code#20873 proposes simple flags like
--no-mcp,--no-plugins, and--vanillafor clean sessions. As of April 2026, these flags are not yet implemented (labeled as stale/enhancement).gh-aw Frontmatter — No
.mcp.jsonSkip OptionReviewing the gh-aw frontmatter reference and MCP guide:
mcp-servers:frontmatter section lets you add MCP servers to a workflow, but there is no option to suppress auto-loading of the repo's.mcp.json.gh aw init --no-mcpskips MCP setup during workflow initialization, but is not a runtime option.skip-mcp-json: trueor equivalent frontmatter option.This means a repo's
.mcp.jsonis always picked up by the agent sandbox, regardless of what the workflow's frontmatter declares.disabledMcpServersArray — No CLI SurfaceA
disabledMcpServersarray exists internally in~/.claude.json, but has no CLI surface and is overridden by cloud-synced integrations. Feature request anthropics/claude-code#30595 proposesclaude mcp disable/enablecommands to write to this array.Summary Table
--strict-mcp-config --mcp-config '{}'CLAUDE_MCP_SKIP_WAIT=true.mcp.json--no-mcpflagoptional: trueper server in.mcp.jsonRecommendations
Short-term for gh-aw users: The current workaround (removing
.mcp.jsonfrom VCS / using.gitignore) remains the only reliable option, as there's no gh-aw frontmatter flag to suppress auto-loading.For gh-aw platform: Adding a frontmatter option like
mcp-auto-load: falseorskip-project-mcp: truewould directly address this issue without requiring changes to.mcp.jsonin each affected repo.For Claude Code upstream: The
optional: trueper-server flag proposed in this issue, or the--no-mcpCLI flag from anthropics/claude-code#20873, would be the cleanest fix. gh-aw could then pass--strict-mcp-config --mcp-config '{}'for workflows that don't declare any MCP servers.Immediate mitigation: gh-aw could potentially inject
CLAUDE_MCP_SKIP_WAIT=trueinto the sandbox environment to prevent MCP connection failures from being fatal blockers — though theERR_APIannotation behavior would need to be investigated separately.Key Sources
--no-mcpflag--strict-mcp-configbug withdisabledMcpServersclaude mcp disable/enablefeature request--strict-mcp-config]((paddo.dev/redacted)References: §24242744787
pelikhan commentedon Oct 7, 2026
Status (2026-10-07; Maintainer direction): On March 20, a maintainer said unrelated MCP servers should not be loaded automatically; the April 10 research identified Claude Code flags that may prevent
.mcp.jsondiscovery but reported no gh-aw workflow-level control. The next step is to verify the applicable engine behavior and determine how gh-aw should disable unwanted auto-loading without suppressing servers explicitly requested by a workflow.pelikhan commentedon Oct 16, 2026
Current-state refresher (2026-10-16): the Claude path is addressed; the original run still needs engine-specific confirmation. #64970 merged on October 2. The current Claude argument builder always adds
--strict-mcp-config, and supplies the generated workflow MCP configuration when servers are explicitly configured. Regression assertions cover strict mode even when no workflow MCP servers are configured; additional cases cover configured servers/safe outputs.This supersedes the April research's claim that removing the repository's
.mcp.jsonis the only available mitigation for Claude workflows. It isolates discovery rather than making arbitrary auto-discovered failures non-fatal, preserving explicitly declared servers.The report does not establish the engine/version used, and I did not access or rerun the private failing workflow. Accordingly, this is partially addressed, not a confirmed end-to-end resolution for every engine. Confirming a newly compiled affected Claude workflow would determine whether anything remains beyond the implemented isolation.
pelikhan commentedon Oct 22, 2026
Relevance check (2026-10-22): Claude isolation is implemented; keep open for engine-specific confirmation of the original report. #64970 merged on October 2. Current
main(ffdd9c9) always passes--strict-mcp-configto Claude, using the generated workflow MCP config when needed. Tests cover no configured servers and explicit servers/safe outputs. Thus removing.mcp.jsonfrom version control is no longer the only mitigation on the Claude path; unrelated discovery is suppressed rather than its failures being silently ignored.Next concrete action/evidence requested: identify the original engine and CLI/compiler versions, and share sanitized generated invocation/config plus the MCP startup/error excerpt from a currently recompiled affected workflow. The confirming case should retain a deliberately unavailable server in repository
.mcp.json, omit it from workflow tools, and still keep explicitly declared workflow MCP servers working. If current Claude strict mode passes that case, close this report as completed; if not, isolate the affected engine/version and whether the unexpected server came from repository, user, or generated configuration. The private failed run was not inspected or rerun in this assessment; no cross-engine resolution is claimed.