Cómo humanizar un documento de Word dentro de Claude Code

HumanPen incluye un servidor MCP stdio local. Todos los clientes arrancan el mismo comando, `npx -y humanpen-mcp`, con una variable de entorno que guarda la clave de API. El agente pasa una ruta absoluta a un `.docx` en lugar de su texto, así que el documento nunca entra en la ventana de contexto, y el archivo reescrito se escribe de vuelta en el disco.

No hay endpoint remoto ni envoltorio de gateway por delante. Si has usado `mcp-remote` o `supergateway` para otros servidores, aquí no necesitas ninguno de los dos.

El diseño obvio es aceptar una cadena y devolver una cadena. También es el diseño que se viene abajo justo con los documentos que la gente de verdad quiere reescribir.

Un `.docx` es un zip de partes XML. Meter los bytes en una conversación no te da nada aprovechable, y descomprimirlo dentro del contexto descarta precisamente la estructura que hacía que valiera la pena conservarlo como archivo: estilos de encabezado, objetos de tabla, partes de notas al pie, los campos que hay detrás de un índice. Aplanar una tesis a una cadena, reescribir la cadena, y habrás resuelto el problema equivocado. Campos de Word, índices y referencias cruzadas explica lo que cuesta ese viaje de ida y vuelta.

Así que la llamada a la herramienta lleva una ruta de entrada y una ruta de salida. El archivo se sube por HTTPS, se procesa y el resultado se escribe de vuelta en tu disco. Nada grande toca tu ventana de contexto.

La vía más rápida es dejar que lo haga el agente. La página de desarrolladores te da una línea lista para copiar que apunta tu cliente a la guía de instalación de MCP; la pegas y el agente descarga la guía, averigua qué archivo de configuración lee tu cliente y te pide una clave.

A mano, en Claude Code basta una línea:

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

El `-s user` importa más de lo que parece. El ámbito por defecto es `local`, que registra el servidor solo para el directorio donde ejecutaste el comando. Al día siguiente abres Claude Code en otro sitio, no encuentras ninguna herramienta de HumanPen y concluyes, con toda la razón, que la instalación falló.

Codex lee `~/.codex/config.toml`, donde el mismo servidor es una tabla `[mcp_servers.humanpen]` con `command = "npx"`, `args = ["-y", "humanpen-mcp"]` y `env = { HUMANPEN_API_KEY = "hp_your_key" }`. La guía de instalación tiene el bloque para copiar.

Cursor, Windsurf, Cline y Claude Desktop adoptan la misma forma en sus propios archivos de configuración. Una trampa en las aplicaciones de escritorio: pon la ruta absoluta de `npx` en `command`. Ejecuta `which npx` y usa el resultado. El sistema operativo lanza estas aplicaciones con un `PATH` mínimo, el nombre a secas muchas veces no se encuentra y el único síntoma es que las herramientas no aparecen nunca.

Después de reiniciar aparecen ocho herramientas. La que importa en este artículo es `humanize_document`; `read_detection_report` y `check_job` son las dos que la acompañan.

La razón para hacerlo desde un agente y no desde un formulario web es que el agente ya tiene tus archivos, incluido el informe de detección que está en la misma carpeta.

Entrégale ambas cosas al trabajo. Si hay un informe adjunto y no se da una lista explícita de pasajes, los pasajes marcados en ese informe pasan a ser el alcance de la reescritura y todo lo demás del documento queda intacto. Si en cambio das una lista explícita, esa lista es definitiva y el informe se conserva solo como adjunto del trabajo. Por la API REST lo mismo se ve así, contra la raíz de API que te muestra la página de desarrolladores:

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

Los créditos se cuentan sobre las palabras realmente reescritas, así que un trabajo delimitado por un informe con cuatro párrafos marcados se cobra como cuatro párrafos. Las vías Skill, MCP y API consumen el mismo saldo, y un trabajo que no termina no se cobra.

El modelo nunca ve el resultado.

Lo que devuelve una llamada terminada es un recibo del trabajo: dónde se escribió el archivo, cuánto costó y cómo se movió el recuento de palabras. Ni contenido ni diff. Todo lo que querías dirigir tiene que estar escrito en la cadena de instrucciones antes de que empiece el trabajo, a ciegas.

La respuesta habitual es que el cliente tiene una herramienta de lectura de archivos, así que el agente puede leer el resultado. Puede leer las palabras: cinco líneas de `python-docx` sacan el texto de los párrafos y lo comparan con el original. Lo que no puede leer es si el formato sobrevivió, y el formato es la razón por la que enviaste un archivo y no una cadena. Así que el agente puede decirte que un trabajo salió bien, cuánto costó y qué dice ahora el texto. No puede decirte si la tabla de la página 7 llegó intacta.

Esa comprobación es tuya, en Word, y es la misma comprobación que después de cualquier reescritura: actualizar campos, contar entradas de la bibliografía, leer las celdas que llevan números. Cómo revisar un documento de Word humanizado antes de entregarlo tiene la versión completa.

Reescribir un documento real tarda minutos, y eso es incómodo dentro de un protocolo pensado para llamadas rápidas. Una llamada espera unos 55 segundos y luego devuelve un id de trabajo en vez de un archivo. El trabajo sigue corriendo en el servidor y `check_job` lo recoge.

De ahí salen dos cosas, y ambas conviene saberlas antes de construir un bucle a su alrededor. Si el timeout de tu propio cliente es más corto que la espera, la petición muere de tu lado mientras el trabajo sigue corriendo del nuestro, y la salida es `check_job` con el id que no recibiste.

Y una llamada que devuelve un archivo y una llamada que devuelve un id son la misma llamada, así que cualquier automatización a su alrededor tiene que manejar ambos resultados en vez de asumir que vuelve un documento.

Para dos párrafos que querías dejar ordenados, esta es la forma equivocada. Pagas una subida de archivo, un trabajo, una espera y una descarga por algo que podías haber leído con tus propios ojos.

La balanza se inclina al otro lado con un capítulo entero: el archivo nunca entra en el contexto, nunca se aplana a una cadena por el camino y el alcance puede definirlo un informe de detección en vez de tu mano. En algún punto entre esos dos extremos hay una línea, y el servidor no tiene forma de saber de qué lado estás. Tú sí.

¿Con qué clientes funciona esto? Con cualquier cliente MCP que pueda arrancar un comando local. Las configuraciones documentadas cubren Claude Code, Codex, Cursor, Windsurf, Cline, Claude Desktop, VS Code, OpenCode y algunos más, y el trato para cualquier otro es ejecutar `npx -y humanpen-mcp` con `HUMANPEN_API_KEY` en su entorno.

¿Necesito una suscripción aparte para el servidor MCP? No. Skill, MCP y REST consumen el mismo saldo de créditos, y los créditos se cuentan sobre las palabras realmente reescritas.

¿Puede el agente verificar el resultado? El formato no. La llamada vuelve con un recibo del trabajo en vez del documento, y una herramienta de lectura de archivos puede recuperar la prosa pero no si los campos, las tablas y los estilos sobrevivieron. Esa inspección es un paso que haces tú en Word.

¿Por qué mi llamada devolvió un id de trabajo en vez de un archivo? Porque el trabajo se salió de la ventana de espera, que es de unos 55 segundos. El trabajo continúa en el servidor; `check_job` con ese id devuelve el resultado cuando está listo.