docs: clarify two-layer MCP timeout config (#2)#3
Merged
Conversation
Document that the MCP client (Claude Code) has its own tool-call timeout separate from agy's per-tool budget; if it's shorter, the client gives up with 'timed out waiting for response' while the agy session keeps running. Adds a 'Two timeout layers — align them' section with the per-server .mcp.json timeout example, the client >= agy rule, and an expected-latency note (~40-50s cold start) so users size client timeouts correctly. Closes #2
Switch the install command to 'claude mcp add-json' with a baked-in "timeout": 600000 so users get a 10-min client-side tool-call deadline at install time, instead of discovering it only after a timeout. Note the MCP_TOOL_TIMEOUT env fallback for clients that don't honor per-server timeout.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #2.
What
Documents that there are two separate timeouts at play and they must be aligned:
Error: timed out waiting for responseAdds a "Two timeout layers — align them" section to the README with:
.mcp.json"timeout"example +MCP_TOOL_TIMEOUTnoteclient timeout >= agy budgetrule of thumbWhy
The reporter hit a client timeout below agy's
analyze_filesbudget, so Claude Code gave up while the agy session kept running (recoverable viafollow_up). The fix is config, not code — but the client-side layer was undocumented.Verification
Reproduced from scratch by driving the MCP server over stdio and varying only the client read deadline:
timed out waiting for responseDocs-only change — no code touched.