MCP tools can't accept large files as arguments — pass a path instead
StelaSpace explains why MCP tool arguments can't carry large files — they're emitted token-by-token by the model — and shows a one-line fix: accept a file path and let the server read from disk.
Score breakdown
Any MCP tool designed to receive bulk content as an argument will silently fail or corrupt data at real-world file sizes, making the path-reference pattern a required design constraint rather than an optional optimization.
- 01MCP tool arguments are tokens emitted by the model, not file handles or pointers.
- 021 MB of HTML is roughly 250k–350k tokens, exceeding typical model max output limits.
- 03Failure modes include truncated tool calls, silently corrupted/abbreviated HTML, and refusal-like stalls.
StelaSpace built an MCP server (`stelaspace-mcp` on npm, MIT licensed) that publishes HTML files, and discovered a fundamental constraint of MCP tool calling: arguments are text the model emits token by token inside its response. A tool that accepts `html: z.string()` works fine on small inputs, but on a real artifact — a 1.4 MB dashboard with inlined data — the call fails. At roughly 250k–350k tokens per MB of HTML, the payload exceeds typical model output limits, producing truncated tool calls that fail to parse, silently corrupted HTML where the model abbreviates content, or stall-like refusals. Even when a file technically fits, the author notes it incurs expensive output-token pricing.
The fix is a single design change: replace the `html` argument with a `path` argument.
The fix is a single design change: replace the `html` argument with a `path` argument. The model's tool call shrinks to roughly 50 tokens (just the absolute file path and a title), and the server uses `fs.readFile` to load the content from disk before uploading via multipart. This works cleanly for local stdio servers because the server and the agent share the same filesystem. The author extends the principle into a general audit rule for MCP tool design: wherever a tool argument could grow large — file contents, datasets, images, full documents — accept a reference (path, URL, or query) instead, and let the server resolve it. The same logic applies to tool outputs: returning a huge payload forces the model to process it as tokens too.
Key facts
- 01MCP tool arguments are tokens emitted by the model, not file handles or pointers.
- 021 MB of HTML is roughly 250k–350k tokens, exceeding typical model max output limits.
- 03Failure modes include truncated tool calls, silently corrupted/abbreviated HTML, and refusal-like stalls.
- 04The fix: accept a file `path` (z.string()) instead of file contents; the server reads from disk with `fs.readFile`.
- 05The model's tool call shrinks to ~50 tokens regardless of file size when using a path reference.
- 06Local stdio MCP servers share the same filesystem as the agent, making the path-reference pattern practical.
- 07The server is published as `stelaspace-mcp` on npm under the MIT license.
Topics
Summary and scoring are generated automatically from the original article. We always link back to the publisher and never republish images or paywalled content. Last processed Jun 12, 2026 · 10:05 UTC. How this works →