{"slug": "your-mcp-server-can-t-take-a-file-as-an-argument-here-s-why-and-the-fix", "title": "Your MCP server can't take a file as an argument — here's why, and the fix", "summary": "A developer building an MCP server for publishing HTML files discovered that large files cannot be passed as tool arguments because the model must emit the entire argument token by token, hitting output token limits. A 1.4 MB dashboard failed where a 5 KB test succeeded, revealing that tool arguments are bounded by the model's maximum output tokens. The fix replaces file contents with a file path reference, reducing the tool call to roughly 50 tokens regardless of file size.", "body_md": "I built an MCP server that publishes HTML files, and I hit a wall I haven't\n\nseen documented anywhere: **you can't pass a large file as an MCP tool\nargument.** Not \"it's slow\" or \"it's awkward\" — the model is physically\n\nHere's the failure, why it happens, and the one-line design change that fixes it.\n\nMy agents (Claude Code, mostly) generate a lot of interactive HTML — dashboards\n\nwith Chart.js, data-heavy reports, PRDs. I wanted them to publish those files to\n\nthe web with one tool call, so I did the obvious thing first:\n\n```\nserver.tool(\n  \"publish_html\",\n  { html: z.string(), title: z.string() },\n  async ({ html, title }) => {\n    const url = await upload(html, title);\n    return { content: [{ type: \"text\", text: url }] };\n  }\n);\n```\n\nThe agent generates the HTML, passes it as the `html`\n\nargument, the server\n\nuploads it. It demoed beautifully on a 5 KB \"hello world\" page.\n\nThen I tried it on a real artifact — a 1.4 MB dashboard with inlined data —\n\nand it fell apart.\n\nWhen a model calls a tool, the arguments aren't a file handle or a pointer.\n\nThey are **text the model emits, token by token**, inside its response. A tool\n\ncall's arguments are part of the model's output, which means they're bounded by\n\nthe model's maximum output tokens.\n\nDo the math: 1 MB of HTML is roughly 250k–350k tokens. Typical max output is\n\nfar below that. The model literally cannot finish \"saying\" the argument. In\n\npractice you get one of:\n\nAnd even when a file *fits*, you're paying output-token prices (the expensive\n\nones) to make the model retype a file that already exists on disk, byte for\n\nbyte, with a nonzero chance of it \"fixing\" something along the way.\n\nThis isn't an MCP bug. It's the nature of tool calling: **arguments are model\noutput**. Any MCP tool designed to receive bulk content as an argument has a\n\nThe server runs locally over stdio. It has the same filesystem the agent is\n\nworking in. So the tool takes a **path**:\n\n```\nserver.tool(\n  \"publish_file\",\n  {\n    path: z.string().describe(\"Absolute path to the HTML file to publish\"),\n    title: z.string(),\n  },\n  async ({ path, title }) => {\n    const html = await fs.readFile(path, \"utf8\"); // server reads from disk\n    const url = await uploadMultipart(html, title); // server does the upload\n    return { content: [{ type: \"text\", text: url }] };\n  }\n);\n```\n\nNow the model's tool call is ~50 tokens regardless of file size:\n\n```\n{ \"path\": \"/Users/me/reports/q2-dashboard.html\", \"title\": \"Q2 Dashboard\" }\n```\n\nThe agent never carries the bytes. It writes the file with its normal file\n\ntools (which stream and don't have this constraint the same way), then hands\n\nthe *reference* to the MCP server, which reads from disk and does a multipart\n\nupload itself. 1.4 MB or 14 MB — the model's job is the same size.\n\nThis one design decision is the difference between a demo that works on toy\n\nfiles and a tool that's useful on real artifacts.\n\nIf you're building an MCP server, audit every tool argument and ask: *could\nthis be big?* If yes, take a reference instead:\n\n| Instead of accepting… | Accept… |\n|---|---|\n| file contents | a file path |\n| a big dataset | a path, URL, or query the server executes |\n| an image/binary blob | a path or URL |\n| \"the whole document\" to edit | a path + edit instructions |\n\nThe corollary for *outputs* is the same: a tool that returns a huge payload\n\nfills the model's context window. Return a reference (a URL, a path, a\n\nsummary + handle) and let the model fetch slices if it needs them.\n\nLocal stdio servers are perfect for this pattern because they share a\n\nfilesystem with the agent. For remote MCP servers you'd reach for the same\n\nidea with URLs or pre-signed uploads — anything but the bytes-in-arguments\n\ntrap.\n\nThe server is `stelaspace-mcp`\n\non npm (MIT) — it publishes HTML files to\n\n[StelaSpace](https://stelaspace.com), which gives each artifact a permanent,\n\nsandboxed, access-controlled link (I built it; free tier exists). One-line\n\nsetup with Claude Code:\n\n```\nclaude mcp add stelaspace --scope user \\\n  --env STELASPACE_API_KEY=ss_sk_... \\\n  -- npx -y stelaspace-mcp\n```\n\nHere's [a live dashboard published this way](https://stelaspace.com/t/demo-team/s/examples/d/sprint-dashboard) —\n\n1 MB+ of interactive Chart.js HTML that no model could ever have passed as a\n\ntool argument.\n\nIf you've hit other walls building MCP servers, I'd genuinely like to hear\n\nthem — I'm collecting these gotchas.", "url": "https://wpnews.pro/news/your-mcp-server-can-t-take-a-file-as-an-argument-here-s-why-and-the-fix", "canonical_source": "https://dev.to/stelaspace/your-mcp-server-cant-take-a-file-as-an-argument-heres-why-and-the-fix-13no", "published_at": "2026-06-12 08:19:31+00:00", "updated_at": "2026-06-12 08:42:20.219270+00:00", "lang": "en", "topics": ["ai-agents", "large-language-models", "ai-tools", "ai-infrastructure", "ai-products"], "entities": ["Claude Code", "Chart.js", "MCP"], "alternates": {"html": "https://wpnews.pro/news/your-mcp-server-can-t-take-a-file-as-an-argument-here-s-why-and-the-fix", "markdown": "https://wpnews.pro/news/your-mcp-server-can-t-take-a-file-as-an-argument-here-s-why-and-the-fix.md", "text": "https://wpnews.pro/news/your-mcp-server-can-t-take-a-file-as-an-argument-here-s-why-and-the-fix.txt", "jsonld": "https://wpnews.pro/news/your-mcp-server-can-t-take-a-file-as-an-argument-here-s-why-and-the-fix.jsonld"}}