MCP gateway tool timeout should be configurable by reusable workflow components

[szabta89]

Problem

Repo Mind Light exposes a long-running HTTP MCP tool through GitHub Agentic Workflows. Some valid repo-mind.query calls take longer than the MCP gateway's default tool read timeout, especially when the server is warming preloaded query sources or synthesizing answers over a large repository index.

Today the only reliable workaround we have found is for every consuming workflow to set:

sandbox:
  mcp:
    env:
      MCP_GATEWAY_TOOL_TIMEOUT: "XXX"

That works, but it is not a good reusable-component contract. A shared Repo Mind Light agentic workflow cannot hide this requirement from consumers, so each consumer needs to know an internal gh-aw-mcpg environment variable and remember to configure it manually.

Why this matters

Repo Mind Light AW is packaged as a reusable shared workflow. The shared workflow can define the HTTP MCP server, start the Repo Mind Light container in pre-agent-steps, wait for readiness via /preload-status, and expose only the query tool.

The missing piece is that the shared workflow cannot reliably set the MCP gateway tool read timeout for its consumers. Without that timeout, users can see query failures even though the Repo Mind Light server is healthy and the workflow has correctly waited for readiness.

This is especially painful because the visible gh-aw-level timeout configuration looks like it should be enough:

tools:
  timeout: 600
  startup-timeout: 600

But in practice those values do not configure the gh-aw-mcpg container's tool read timeout. The gateway still needs MCP_GATEWAY_TOOL_TIMEOUT.

Reproduction / observed behavior

Environment:

• gh-aw v0.71.5
• gh-aw-mcpg v0.3.6
• HTTP MCP server configured in a reusable shared workflow
• Repo Mind Light server started by pre-agent-steps, then exposed through:

mcp-servers:
  repo-mind:
    url: http://127.0.0.1:8000/mcp
    allowed:
      - query

tools:
  timeout: 600
  startup-timeout: 600

We tried adding this to the imported shared workflow:

env:
  MCP_GATEWAY_TOOL_TIMEOUT: "600"

The compiled workflow did include MCP_GATEWAY_TOOL_TIMEOUT as workflow/job env, but the generated MCP gateway Docker command did not pass it into the gh-aw-mcpg container. The generated command lacked -e MCP_GATEWAY_TOOL_TIMEOUT.

By contrast, setting this in the consumer workflow works:

sandbox:
  mcp:
    env:
      MCP_GATEWAY_TOOL_TIMEOUT: "600"

With that consumer-side config, the generated lockfile contains:

export MCP_GATEWAY_TOOL_TIMEOUT=600
...
docker run ... -e MCP_GATEWAY_TOOL_TIMEOUT ... ghcr.io/github/gh-aw-mcpg:v0.3.6

Desired behavior

Reusable MCP components should be able to configure the effective tool read timeout without requiring every consumer to know about MCP_GATEWAY_TOOL_TIMEOUT.

Possible fixes could be any of these, or another design that fits gh-aw/gh-aw-mcpg better:

1. gh-aw-mcpg honors the workflow/server/tool timeout passed in its generated config, so tools.timeout: 600 actually controls MCP tool read timeout.
2. gh-aw-mcpg supports per-server or per-tool timeout configuration in the MCP server JSON config.
3. gh-aw supports import-merged MCP gateway configuration and passes it through to gh-aw-mcpg.
4. The gateway default read timeout is raised or made adaptive for HTTP MCP servers.

The important requirement is that a reusable shared workflow wrapping an HTTP MCP server can set an appropriate default once, while consumers can still override it when needed.

Expected outcome

A Repo Mind Light consumer should be able to import the shared workflow and get a sane MCP gateway timeout by default, without adding hidden implementation-specific config such as:

sandbox:
  mcp:
    env:
      MCP_GATEWAY_TOOL_TIMEOUT: "600"

Consumers may still override the timeout explicitly, but they should not need to do so for the shared component to work reliably.

[lpcox]

Existing frontmatter configuration for MCP gateway tool timeout

gh-aw already supports configuring the MCP gateway tool timeout via frontmatter (available since v0.71.4):

engine:
  mcp:
    tool-timeout: "10m"   # Go duration string — controls the mcpg HTTP backend request timeout

This value is propagated to the gateway's stdin JSON config as toolTimeout and overrides the 60s default.

How it differs from tools.timeout

Field	Controls	Consumed by
tools.timeout: 600	Agent CLI tool timeout (GH_AW_TOOL_TIMEOUT env var)	Copilot/Claude/Codex CLI inside the agent container
engine.mcp.tool-timeout: "10m"	MCP gateway HTTP backend timeout	gh-aw-mcpg container

Both should be set for long-running MCP tools like Repo Mind Light:

tools:
  timeout: 600

engine:
  mcp:
    tool-timeout: "10m"

The gap: shared workflow importability

The core issue here is that engine.mcp.tool-timeout lives under the engine: section, which is not imported from shared workflows. Only tools: block fields (like timeout and startup-timeout) are merged during shared workflow import.

So today, a shared Repo Mind Light workflow cannot set engine.mcp.tool-timeout on behalf of its consumers — they must add it themselves.

Workaround (current)

The sandbox.mcp.env.MCP_GATEWAY_TOOL_TIMEOUT approach described in the issue works but leaks implementation details. Using engine.mcp.tool-timeout in the consumer workflow is the cleaner equivalent:

# Consumer workflow — cleaner than sandbox.mcp.env
engine:
  mcp:
    tool-timeout: "10m"

Possible solutions for shared workflow propagation

1. Make engine.mcp.tool-timeout importable from shared workflows — merge it during import like tools.timeout
2. Add a tools.mcp-timeout alias that maps to the same gateway config — lives in the importable tools: block
3. Per-server timeout in mcp-servers: — e.g. mcp-servers.repo-mind.timeout: "10m" (most granular, most complex)

Any of these would let a shared workflow set a sane default without consumers needing to know about gateway internals.

[szabta89]

Would it be possible to make option (1) work?