How to humanize a Word document inside Claude Code

HumanPen ships a local stdio MCP server. Every client starts the same command, `npx -y humanpen-mcp`, with one environment variable holding the API key. The agent passes an absolute path to a `.docx` rather than its text, so the document never enters the context window, and the rewritten file is written back to disk.

There is no remote endpoint and no gateway wrapper in front of it. If you have used `mcp-remote` or `supergateway` for other servers, you do not need either here.

The obvious design is to accept a string and return a string. It is also the design that falls apart on the documents people actually want rewritten.

A `.docx` is a zip of XML parts. Reading the bytes into a conversation gets you nothing usable, and unzipping it into the context throws away exactly the structure that made it worth keeping as a file: heading styles, table objects, footnote parts, the fields behind a table of contents. Flatten a thesis to a string, rewrite the string, and you have solved the wrong problem. Word fields, tables of contents and cross-references covers what that round trip costs.

So the tool call carries a path in and a path out. The file is uploaded over HTTPS, processed, and the result written back to your disk. Nothing large touches your context window.

The fastest route is to let the agent do it. The developers page hands you a ready-to-copy line that points your client at the MCP install guide; paste it in and the agent fetches the guide, works out which config file your client reads, and asks you for a key.

By hand, Claude Code is one line:

claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp

The `-s user` matters more than it looks. The default scope is `local`, which registers the server only for the directory you ran the command in. You will open Claude Code somewhere else the next day, find no HumanPen tools, and reasonably conclude the install failed.

Codex reads `~/.codex/config.toml`, where the same server is an `[mcp_servers.humanpen]` table with `command = "npx"`, `args = ["-y", "humanpen-mcp"]` and `env = { HUMANPEN_API_KEY = "hp_your_key" }`. The install guide has the block to copy.

Cursor, Windsurf, Cline and Claude Desktop take the same shape in their own config files. One trap in the desktop apps: put the absolute path to `npx` in `command`. Run `which npx` and use that. These apps are launched by the OS with a minimal `PATH`, the bare name often is not found, and the only symptom is that the tools never appear at all.

After a restart, seven tools show up. The one this post is about is `humanize_document`; `read_detection_report` and `check_job` are the two that support it.

The reason to do this from an agent rather than a web form is that the agent already has your files, including the detection report sitting in the same folder.

Hand the job both. When a report is attached and no explicit passage list is given, the passages flagged in that report become the rewriting scope, and everything else in the document is left alone. Give an explicit list instead and that list is final, with the report kept only as an attachment on the job. Over the REST API the same thing looks like this, against the API root the developers page shows you:

curl -X POST "$HP_API_ROOT/jobs/humanize" -H "Authorization: Bearer $HP_API_KEY" -F "file=@paper.docx" -F "turnitin_file=@turnitin-report.pdf" -F "strategy=balanced" -F "additional_instructions=Keep terminology and citations unchanged."

Credits are counted on the words actually rewritten, so a report-scoped job on four flagged paragraphs is priced as four paragraphs. The Skill, MCP and API paths all spend the same balance, and a job that does not complete is not charged.

The model never sees the output.

What a finished call hands back is a receipt for the job: where the file was written, what it cost, and how the word count moved. No content, no diff. Whatever you wanted steered has to be written into the instructions string before the job starts, blind.

The usual reply is that the client has a file read tool, so the agent can just read the result. It can read the words: five lines of `python-docx` will pull the paragraph text out and diff it against the original. What it cannot read is whether the formatting survived, and the formatting is the reason you sent a file instead of a string. So the agent can tell you a job succeeded, what it cost, and what the prose now says. It cannot tell you whether the table on page 7 came through.

That check is yours, in Word, and it is the same check as after any rewrite: refresh fields, count reference entries, read the cells with numbers in them. How to review a humanized Word document before submission has the full version.

Rewriting a real document takes minutes, which is awkward inside a protocol built around fast tool calls. A call waits about 55 seconds and then returns a job id instead of a file. The work keeps running on the server, and `check_job` picks it up.

Two things follow from that, and both are worth knowing before you build a loop around it. If your client's own timeout is shorter than the wait, the request dies on your side while the job keeps running on ours, and the recovery is `check_job` with the id you did not get.

And a call that returns a file and a call that returns an id are the same call, so anything automated around it has to handle both outcomes rather than assuming a document comes back.

For two paragraphs you wanted tidied, this is the wrong shape. You pay a file upload, a job, a wait, and a download, for something you could have read with your own eyes.

The trade turns the other way on a whole chapter: the file never enters the context, it is never flattened into a string on the way through, and the scope can be defined by a detection report instead of by hand. Somewhere between those two is a line, and the server has no way to tell which side of it you are on. You do.

Which clients does this work with? Any MCP client that can start a local command. The documented configurations cover Claude Code, Codex, Cursor, Windsurf, Cline, Claude Desktop, VS Code, OpenCode and a few others, and the contract for anything else is to run `npx -y humanpen-mcp` with `HUMANPEN_API_KEY` in its environment.

Do I need a separate subscription for the MCP server? No. Skill, MCP and REST all spend the same credit balance, and credits are counted on the words actually rewritten.

Can the agent verify the result? Not the formatting. The call comes back with a receipt for the job rather than the document, and a file read tool can recover the prose but not whether the fields, tables and styles survived. That inspection is a step you do yourself in Word.

Why did my tool call return a job id instead of a file? Because the job outran the wait window, which is about 55 seconds. The job continues on the server; `check_job` with that id returns the result when it is ready.