MCP Tool Call Result Truncated: Causes, Pagination, Cursors, and Size Limits

Direct answer: Tool call result truncated usually does not mean that MCP defines one universal 64KB result limit. A client display cap, tool-result cap, model context budget, serialized message size, transport backpressure, or timeout may be the first layer to fail. Return bounded results with total counts and a cursor or offset instead of silently cutting text, then let the model request the next page or a targeted range.

Version note — 2026-08-10: MCP 2026-07-28 is now published, and the protocol still does not define one universal 64KB Tool Result ceiling. The TypeScript SDK v2 migration guide adds a configurable stdio maxBufferSize with a 10 MB default. That is an SDK read-buffer boundary, not a protocol-wide tool-result limit, so production debugging must keep protocol rules separate from client and SDK implementation limits.

What This Guide Covers: The Physical Limits of Information Loss

• Why did Cursor prompt Tool call result truncated when my MCP Server was reading a log file containing 1MB?
• How can I gracefully inform the AI that “there is more content to read” before the Stdio buffer overflows?
• Why does simple physical truncation (e.g., text[:5000]) cause the AI to hallucinate?
• How do you design a “perceptive” streaming feedback mechanism when processing massive database query results?

---

Who This Guide Is For

• AI System Developers: Those writing custom MCP Servers involving large-scale data interactions.
• Agent Architects: Those needing to solve the “context anemia” problem Agents face when handling long documents or logs.
• Full-Stack Engineers: Developers frequently encountering protocol-level errors or response timeouts while debugging local private cloud Agents.

---

1. Diagnose the Correct Layer: Protocol, Client, Context, or Transport

When a large result fails, do not begin with the assumption that “MCP only supports 64KB.” The MCP stdio transport requires the client and server to exchange valid newline-delimited JSON-RPC messages over stdin and stdout; the specification does not define one universal 64KB tool-result ceiling. A reproducible test should instead increase fixture size gradually and record raw bytes, serialized bytes, bytes received by the client, elapsed time, and the layer that emitted the failure.

The investigation must separate client display or injection limits, the remaining model context budget, serialized JSON size, whether the host process consumes stdout promptly, and whether the tool finishes before its timeout. An operating-system pipe buffer can create backpressure, but it is not an MCP rule that automatically truncates every message above one fixed byte count.

Record the raw result size, serialized message size, received size, elapsed time, and any client truncation marker before choosing pagination, cursor-based continuation, range queries, summaries, or an object-storage link. MCP’s standard cursor pagination applies to list operations such as resources/list and tools/list; a custom Tool that returns large data should define its own cursor or offset, bounded page size, and explicit has_more field in the Tool schema.

---

2. Solution A: Physical Pagination and Secondary Invocation

Don’t try to feed the AI everything at once; teach it how to “turn the page.”

1. Implementing an Offset Mechanism

When writing Tool logic, enforce the requirement for offset and limit parameters.

@app.call_tool("read_large_file")
def read_large_file(path: str, offset: int = 0, limit: int = 5000):
    with open(path, 'r') as f:
        f.seek(offset)
        content = f.read(limit)

        has_more = f.tell() < os.path.getsize(path)

        return {
            "content": content,
            "metadata": {
                "next_offset": f.tell() if has_more else None,
                "status": "partial_success" if has_more else "complete"
            }
        }

2. Injecting “Pagination Logic” into the System Prompt

You must explicitly instruct the AI: “If you detect that metadata.status is partial_success, you must proactively call for the next page. Do not speculate based on incomplete information.”

---

3. Solution B: Semantic Compression (The Semantic Shrink)

Physical truncation is blunt; it severs the logical chain. The truly robust approach is to perform “perceptive compression” on the server side.

Key Point: Don’t let the AI read raw data; make it read an “audit report.”

For large logs, generate a traceable index before asking the model to inspect raw text. A practical pattern is:

1. Deduplicate by error type, stack fingerprint, or business error code while preserving occurrence counts.
2. Sample startup, failure-window, and tail ranges while retaining original line numbers or timestamps.
3. Index signals such as ERROR, FATAL, and RETRY, but let the caller fetch additional ranges by cursor or time window.
4. Attach source_range, a checksum, or a controlled URI to every summary so the model or reviewer can return to the original evidence.

The purpose is to reduce context pressure without breaking the evidence chain. Compression ratio and diagnostic quality depend on the log structure, filters, model, and task. This article does not contain a controlled benchmark, so it should not claim one fixed compression factor or accuracy improvement.

---

4. Comparison Block: Physical Truncation vs. Logical Compression

• Physical truncation (str[:limit]):
  • Pros: Requires only 1 lines of code and incurs no computational overhead.
  • Cons: May break JSON structure or core logic, leading to AI hallucinations.
• Logical pagination:
  • Pros: Ensures data integrity and gives the AI autonomous decision-making power.
  • Cons: Increases conversation turns and token consumption.
• Semantic summarization:
  • Pros: Most efficient; the AI receives high-quality context in a single pass.
  • Cons: Requires additional server-side compute resources (e.g., invoking a local small model or more complex logic).

---

5. Common Pitfalls and Error Logs

1. Error: JSON-RPC message exceeds max length

• Cause: This is a size limit imposed by a particular client, SDK, proxy, or host application—not a universal 1MB threshold in the MCP specification.
• Solution: Identify the layer that emitted the error and record the serialized message size. Do not embed Base64 images or binary payloads in a Tool Result; return a controlled URI, summary, and bounded read parameters instead.

2. Error: Tool Execution Timeout

• Symptom: The server logic appears to complete, but the client still reports a timeout.
• Investigation: Measure business-query time, JSON serialization time, write time, and the client timeout separately. The cause may be the query itself, oversized messages, transport backpressure, or a host timeout; the symptom alone does not prove that stdout crossed one fixed buffer limit.

---

6. Frequently Asked Questions

Q: If stdio is affected by local-process and host limits, why not use Streamable HTTP everywhere?

A: The transports serve different deployment boundaries. stdio is appropriate for a local Server launched by the Client and requires no separately exposed port. Streamable HTTP is better for remote or multi-client services that need authentication, sessions, and network observability. Changing transport does not automatically solve oversized Tool Results or insufficient model context.

Q: What if I must provide a 10MB CSV file?

A: Do not embed the complete file in the Tool Result. Save it in an access-controlled location the Client can reach, then return a URI, file size, checksum, schema summary, and allowed read ranges. A separate reader Tool can retrieve only the required rows, chunks, or query results.

Q: How do I know whether the Server or Client truncated a result?

A: Record raw bytes, serialized bytes, bytes received by the Client, a checksum, elapsed time, and an explicit has_more value. Any fixed 100KB or 1MB number is a client-specific configuration until verified; it is not an MCP-wide threshold.

---

Recommended Deep Reading

• Official MCP transport specification: stdio and Streamable HTTP
• Official MCP pagination specification: cursors and paginated list operations
• MCP hub: protocol, servers, deployment, and troubleshooting
• MCP Resources vs Tools vs Prompts vs Roots
• MCP stdio pollution and -32700 Parse Error troubleshooting
• MCP Streamable HTTP deployment: remote transport and security boundaries
• MCP security: tool permissions, paths, and high-risk actions

Topic path / MCP

Continue from protocol details to production MCP governance

The MCP hub connects protocol fundamentals, transports, authentication, security, JSON-RPC debugging and production deployment without splitting the search intent across isolated guides.

Open MCP hub → Review the security checklist Subscribe