# MCP Attachment Base64 Cost: Why AgentRQ Has a Workspace CLI An agent talks to its AgentRQ workspace over MCP. That is the right shape for an agent — typed tools, JSON arguments, a transport it already speaks — and the wrong shape for almost everything else. Every call is an envelope, and every answer is tokens somebody pays for. `agentrq-ws` is the same eleven tools, from a shell: ```bash npx @agentrq/agentrq-ws@latest workspace ``` No install, no configuration, no token to paste. It reads the `.mcp.json` in the directory you run it from — the same file the agent working there uses — so inside a workspace checkout there is nothing to set up. It is published on npm as [@agentrq/agentrq-ws](https://www.npmjs.com/package/@agentrq/agentrq-ws), Apache-2.0, and it shipped in [PR #589](https://github.com/agentrq/agentrq/pull/589). The full reference is in the [Workspace CLI docs](/docs/workspace-cli). This post is about why it exists.  That is a real run against the workspace this post was written in. Eleven tools, no token pasted anywhere — the `.mcp.json` in the repository already had one. ## Where the Cost Comes From Start with the thing that is worst about doing this from inside an agent, because it is the reason the CLI is not just a thinner MCP client. The workspace tools speak base64 in both directions. `createTask` and `reply` take an `attachments` array whose entries look like `{id, filename, mimeType, data}`, and `data` is the whole file, base64-encoded. `downloadAttachment` answers with base64 and nothing else — no name, no media type, just the encoded bytes. So when an agent attaches a build log today, this is what actually happens: 1. It reads the file off disk, into its own context. 2. It base64-encodes it — which means the encoded text is also in its context. 3. It puts that text in the arguments of a tool call. 4. The tool call and its arguments stay in the conversation for the rest of the session, re-sent with every subsequent request. Step 4 is the one that hurts. A tool call is not a cost you pay once. It is part of the transcript, so a 2 MB screenshot attached at the start of a session is still being re-sent at the end of it. And base64 is not free even before that. It encodes three bytes as four characters, so the encoded form is **four-thirds the size** of the file: a 900 KB PDF becomes 1.2 MB of text, a 3 MB screenshot becomes 4 MB. That text is a dense run of alphanumerics with no words in it, which is close to the worst case for any tokenizer — nothing in it compresses the way prose does. Downloading is the same tax in reverse. The agent asks for an attachment, and the answer — the entire encoded file — lands in its context, where it stays. ## What the CLI Does Instead ```bash agentrq-ws reply 0isnjTCkpW5 "Build is green — log attached" --attach ./run.log ``` The encoding happens in the Node process. `readAttachment` reads the path, works out the media type from the extension, base64-encodes the bytes, and hands the result straight to the tool call. The agent's context holds one line of shell and whatever the server says back. Downloading writes a file and prints where it went: ``` $ agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5 /tmp/agentrq-ws-help.txt ``` One path, not four megabytes of alphabet. `--out` takes a directory to keep the attachment's own name, or a full path to rename it. There is a detail worth pointing at, because it is the kind of thing that decides whether a tool is pleasant. `downloadAttachment` returns bytes and no filename — so where does `agentrq-ws-help.txt` come from? The CLI reads the task first, indexes the attachments named in its text and its conversation, and looks the id up. The file arrives called what a human called it. If the task does not mention the id, the download still happens, named after the id, because refusing would be worse than a plainly-named file. ## What This Unlocks **Attachments stop being rationed.** When every file costs context that is never reclaimed, the rational thing for an agent to do is describe a log instead of attaching it, summarize a screenshot instead of sending it, and paste the first forty lines of a stack trace. That is a quiet, constant loss of fidelity, and it happens at exactly the moments when fidelity matters — when something has gone wrong and somebody needs the actual artifact. With the bytes out of the transcript, attaching the whole log is a line of shell, so an agent can hand over the real thing every time. **Anything with a shell can drive a workspace.** The CLI needs no MCP client, no SDK and no long-lived process — just `npx` and a `.mcp.json`. That makes a workspace reachable from places an agent cannot go: a CI job that replies to a task when the build finishes, a cron entry that publishes an event, a git hook that opens a task on a failed push, a `Makefile` target. `task next` claims the next not-started task and dequeues it, so a shell loop is a perfectly good worker. **Humans get the same surface as the agent.** Debugging a workspace used to mean either clicking through the panel or standing up an MCP client. Now it is `agentrq-ws task get --conversation`, and the answer is plain text. When an agent and a person are looking at the same workspace, they can now use the same commands to look at it, which makes "what did it actually see?" a question with a fast answer. **A tool added to the server tomorrow is reachable today.** `agentrq-ws call --args '{…}'` calls anything the server advertises, and `agentrq-ws tools` lists what that is. The CLI does not have to grow a verb before a new capability is usable from a shell. ## The Commands Fourteen commands over the workspace's eleven tools. Every one takes `--help`, and so does every family — `agentrq-ws task --help` lists the task commands, `agentrq-ws attachment get -h` explains that one. | Command | What it does | | --- | --- | | `workspace` | Show the workspace title and mission | | `task get ` | Fetch a task, with `--conversation` for its history | | `task next` | Take the next not-started task — this dequeues the queue | | `task create