[Bug] zread MCP read_file frequently times out while get_repo_structure works — backend unreliable under load
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 22
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
Summary
The read_file tool of the Zread MCP server (https://api.z.ai/api/mcp/zread/mcp) frequently times out (MCP error -32001) or returns spurious "repo not found" errors (code 1210) for repositories that definitely exist and are public. Meanwhile get_repo_structure succeeds at much higher rates on the same repos.
Environment
- Client: OpenCode (MCP streamable HTTP)
- Server URL:
https://api.z.ai/api/mcp/zread/mcp - Plan: GLM Coding Plan (Pro)
- Date tested: 2026-07-16 UTC
Error types observed
| Error | Frequency | Trigger |
|---|---|---|
MCP error -32001: Request timed out |
~60-70% of read_file calls |
Sustained sequential calls, "cold" files/repos |
MCP error -400: {"code":"1210","msg":"repo not found"} |
~20% | Intermittent on repos that exist (e.g. zai-org/feedback) |
500 Internal Server Error |
~5% | Sporadic under load |
Detailed repro
All tests used the same MCP endpoint and API key, tested on 2026-07-16:
Tests that succeeded
| Tool | Repo | Path |
|---|---|---|
get_repo_structure |
nestjs/nest |
(root) |
get_repo_structure |
facebook/react |
(root) |
get_repo_structure |
zai-org/z-ai-sdk-python |
(root) |
read_file |
nestjs/nest |
package.json |
read_file |
nestjs/nest |
packages/core/package.json (after cooldown) |
read_file |
zai-org/z-ai-sdk-python |
src/zai/__init__.py |
Tests that failed
| Tool | Repo | Path | Error |
|---|---|---|---|
read_file |
nestjs/nest |
packages/core/package.json (first try) |
Timeout (-32001) |
read_file |
nestjs/nest |
packages/common/package.json |
Timeout (-32001) |
get_repo_structure |
zai-org/feedback |
(root) | "repo not found" (1210) / timeout |
get_repo_structure |
redis/redis |
(root) | Timeout (-32001) |
get_repo_structure |
fitchmultz/pi-zai-mcp |
(root) | Timeout (-32001) |
read_file |
fitchmultz/pi-zai-mcp |
package.json |
Timeout (-32001) |
Note: this is not a path-depth issue — top-level files fail as often as deeply nested ones. It is backend-load-sensitive: a file that times out on the first attempt usually succeeds after a ~10-15s cooldown.
Root cause suspicion
The backend (zread.ai) appears to have:
- Concurrency limits — back-to-back requests cause cascading timeouts
- No graceful GitHub API rate-limit handling — "repo not found" errors for repos that exist suggest the upstream GitHub API calls are failing silently
- No warm cache — cold files/repos require a slow GitHub API round-trip that exceeds the default client timeout
Workaround (until this is fixed)
get_repo_structure is usable for navigation; for file reads that time out, falling back to https://raw.githubusercontent.com/ works reliably. Adding artificial delays between calls reduces timeout rates but does not eliminate them.
Relevant docs link
The troubleshooting section of the Zread MCP docs (https://docs.z.ai/devpack/mcp/zread-mcp-server.md) mentions "Connection timeout" and suggests increasing client timeout settings, but the issue appears to be server-side, not client-side — the same client succeeds on get_repo_structure while read_file times out on the same server in the same session.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing sequential and cold-call failures against the Zread MCP endpoint, comparing read_file with get_repo_structure and the documented timeout guidance. Done means existing public repositories no longer produce intermittent 1210 errors or timeouts under the reported request patterns, with the listed cases succeeding reliably.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github
- Domain
- api, backend, performance
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100