Claude Code 안에서 Word 문서를 사람이 쓴 글처럼 다듬는 방법

HumanPen은 로컬 stdio MCP 서버를 제공합니다. 모든 클라이언트가 `npx -y humanpen-mcp`라는 같은 명령을, API 키를 담은 환경 변수 하나와 함께 실행합니다. 에이전트는 `.docx`의 텍스트가 아니라 절대 경로를 전달하므로 문서가 컨텍스트 윈도에 들어오지 않습니다. 다시 작성된 파일은 디스크에 기록됩니다.

원격 엔드포인트도, 앞단에 놓인 게이트웨이 래퍼도 없습니다. 다른 서버에서 `mcp-remote`나 `supergateway`를 써 보셨더라도, 여기서는 둘 다 필요하지 않습니다.

가장 떠올리기 쉬운 설계는 문자열을 받아 문자열을 돌려주는 것입니다. 그런데 그것은 사람들이 실제로 다시 작성하고 싶어 하는 문서에서 무너지는 설계이기도 합니다.

`.docx`는 XML 파트를 묶은 zip입니다. 바이트를 대화로 읽어 들여도 쓸 수 있는 것이 없고, 압축을 풀어 컨텍스트에 넣으면 파일로 보관할 가치를 만들었던 구조, 즉 제목 스타일, 표 개체, 각주 파트, 목차 뒤에 있는 필드를 정확히 잃게 됩니다. 학위 논문을 문자열 하나로 납작하게 만들고 그 문자열을 다시 작성하면, 엉뚱한 문제를 푼 셈입니다. 이 왕복의 비용은 Word 필드, 목차, 상호 참조에서 다룹니다.

그래서 이 도구 호출은 경로를 입력으로, 경로를 출력으로 갖습니다. 파일은 HTTPS로 업로드되고, 처리되고, 결과가 여러분의 디스크에 다시 기록됩니다. 큰 것이 컨텍스트 윈도에 닿는 일은 없습니다.

가장 빠른 길은 에이전트에게 맡기는 것입니다. 개발자 페이지는 클라이언트를 MCP 설치 안내서로 이끄는, 복사해 쓰기만 하면 되는 한 줄을 줍니다. 붙여넣으면 에이전트가 안내서를 가져오고, 클라이언트가 어떤 설정 파일을 읽는지 알아내고, 키를 요청합니다.

직접 한다면 Claude Code에서는 한 줄입니다.

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

`-s user`는 겉보기보다 중요합니다. 기본 범위는 `local`인데, 이는 명령을 실행한 디렉터리에만 서버를 등록합니다. 다음 날 다른 곳에서 Claude Code를 열면 HumanPen 도구가 보이지 않고, 설치가 실패했다고 결론짓게 됩니다. 그렇게 판단하시는 것이 충분히 타당합니다.

Codex는 `~/.codex/config.toml`을 읽습니다. 여기서 같은 서버는 `command = "npx"`, `args = ["-y", "humanpen-mcp"]`, `env = { HUMANPEN_API_KEY = "hp_your_key" }`를 담은 `[mcp_servers.humanpen]` 표가 됩니다. 복사할 블록은 설치 안내서에 있습니다.

Cursor, Windsurf, Cline, Claude Desktop도 각자의 설정 파일에서 같은 형태를 취합니다. 데스크톱 앱에는 함정이 하나 있습니다. `command`에 `npx`의 절대 경로를 넣으세요. `which npx`를 실행해 그 결과를 사용하시면 됩니다. 이 앱들은 운영체제가 최소한의 `PATH`로 실행하기 때문에 이름만으로는 찾지 못하는 경우가 많고, 유일한 증상은 도구가 아예 나타나지 않는 것입니다.

다시 시작하면 도구 여덟 개가 나타납니다. 이 글이 다루는 것은 `humanize_document`이고, `read_detection_report`와 `check_job`은 그것을 받쳐 주는 두 도구입니다.

웹 폼이 아니라 에이전트로 하는 이유는, 에이전트가 이미 여러분의 파일을 갖고 있기 때문입니다. 같은 폴더에 있는 탐지 보고서도 이미 갖고 있습니다.

작업에 둘 다 넘기세요. 보고서가 첨부되고 따로 대상 목록을 주지 않으면, 그 보고서에서 표시된 부분이 다시 작성할 범위가 되고 문서의 나머지는 그대로 둡니다. 대신 목록을 명시하면 그 목록이 최종 범위가 되고, 보고서는 작업의 첨부 파일로만 남습니다. REST API에서는 같은 일이 개발자 페이지가 알려 주는 API 루트에 대해 다음과 같이 보입니다.

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."

크레딧은 실제로 다시 작성된 단어 수로 계산되므로, 표시된 단락이 네 개인 보고서로 범위를 정한 작업은 네 단락 요금입니다. Skill, MCP, API 경로 모두 같은 잔액을 쓰고, 끝까지 완료되지 않은 작업은 청구되지 않습니다.

모델은 결과를 전혀 보지 못합니다.

완료된 호출이 돌려주는 것은 작업 영수증입니다. 파일이 어디에 기록됐는지, 비용이 얼마였는지, 단어 수가 어떻게 움직였는지입니다. 본문도, diff도 없습니다. 방향을 잡고 싶었던 내용은 모두 작업이 시작되기 전에, 아무것도 보지 못하는 상태로 지시 문자열에 적어 두어야 합니다.

흔한 반론은 클라이언트에 파일 읽기 도구가 있으니 에이전트가 결과를 읽으면 된다는 것입니다. 단어는 읽을 수 있습니다. `python-docx` 다섯 줄이면 단락 텍스트를 뽑아 원본과 비교할 수 있습니다. 읽을 수 없는 것은 서식이 살아남았는지 여부이고, 그 서식이야말로 문자열이 아니라 파일을 보낸 이유입니다. 그래서 에이전트는 작업이 성공했다는 것, 비용이 얼마였다는 것, 이제 글이 무엇이라고 하는지는 알려 줄 수 있습니다. 7쪽의 표가 무사히 넘어왔는지는 알려 주지 못합니다.

그 확인은 Word에서 하는 여러분의 몫이고, 어떤 다시 작성 뒤에도 하는 것과 같은 확인입니다. 필드를 새로 고치고, 참고 문헌 항목을 세고, 숫자가 든 셀을 읽으세요. 제출 전에 다듬은 Word 문서를 검토하는 방법에 전체 버전이 있습니다.

실제 문서를 다시 작성하는 데는 몇 분이 걸립니다. 빠른 도구 호출을 전제로 만들어진 프로토콜 안에서는 불편한 시간입니다. 호출은 약 55초를 기다린 뒤 파일 대신 작업 ID를 돌려줍니다. 작업은 서버에서 계속 돌아가고, `check_job`이 그것을 이어받습니다.

여기서 두 가지가 따라옵니다. 둘 다 그 주위에 반복문을 만들기 전에 알아 둘 가치가 있습니다. 클라이언트 자체의 타임아웃이 대기 시간보다 짧으면, 요청은 여러분 쪽에서 죽고 작업은 저희 쪽에서 계속 돌아갑니다. 이때의 복구 방법은 받지 못한 ID로 `check_job`을 호출하는 것입니다.

그리고 파일을 돌려주는 호출과 ID를 돌려주는 호출은 같은 호출입니다. 따라서 그 주변을 자동화한다면 문서가 돌아온다고 가정하지 말고 두 결과를 모두 다뤄야 합니다.

정리하고 싶은 단락이 두 개라면, 이 방식은 맞지 않습니다. 눈으로 직접 읽어도 될 일에 파일 업로드, 작업, 대기, 다운로드 비용을 치르는 셈입니다.

한 챕터 전체에서는 계산이 반대로 뒤집힙니다. 파일이 컨텍스트에 들어오지 않고, 지나가는 동안 문자열로 납작해지지도 않으며, 범위를 손으로 정하는 대신 탐지 보고서로 정할 수 있습니다. 그 사이 어딘가에 선이 있겠지만, 여러분이 어느 쪽에 있는지는 서버가 알 방법이 없습니다. 여러분은 아십니다.

어떤 클라이언트에서 동작합니까? 로컬 명령을 실행할 수 있는 MCP 클라이언트라면 어디에서나 동작합니다. 문서화된 설정은 Claude Code, Codex, Cursor, Windsurf, Cline, Claude Desktop, VS Code, OpenCode 등을 다루며, 그 밖의 것에 대한 계약은 환경에 `HUMANPEN_API_KEY`를 두고 `npx -y humanpen-mcp`를 실행하는 것입니다.

MCP 서버에 별도 구독이 필요합니까? 아니요. Skill, MCP, REST 모두 같은 크레딧 잔액을 쓰고, 크레딧은 실제로 다시 작성된 단어 수로 계산됩니다.

에이전트가 결과를 검증할 수 있습니까? 서식은 검증할 수 없습니다. 호출은 문서가 아니라 작업 영수증을 가지고 돌아오고, 파일 읽기 도구로는 글은 복구할 수 있어도 필드와 표와 스타일이 살아남았는지는 알 수 없습니다. 그 점검은 여러분이 Word에서 직접 하시는 단계입니다.

내 도구 호출이 파일 대신 작업 ID를 돌려준 이유는 무엇입니까? 작업이 대기 창, 즉 약 55초를 넘겼기 때문입니다. 작업은 서버에서 계속되고, 해당 ID로 `check_job`을 호출하면 준비되는 대로 결과를 돌려줍니다.