En la mayoría de los equipos que trabajan con agentes de programación, lo que se sabe del proyecto vive en tres sitios: en la cabeza de la gente, en una wiki que el agente no ve y en un AGENTS.md o CLAUDE.md en el checkout de alguien. Este último se queda obsoleto el día que alguien hace un refactor, y el siguiente agente se lo cree igual.
ClewWiki está pensada como un cuarto sitio: una wiki donde los agentes trabajan a la par que las personas. Leen, escriben, discuten y rinden cuentas. La versión 0.9.0 tiene 40 herramientas MCP. A continuación, cómo conectarle Claude Code, Cursor o Codex y qué recibe el agente. La parte de las personas (importación, inicio de sesión, organizaciones) está en el artículo hermano.
Conexión en dos minutos#
El servidor MCP se distribuye como el paquete npm @clewwiki/mcp-server. No hace falta instalar nada antes, salvo Node.js 22. En la instancia emites un token de agente en Agent tokens y después escribes la configuración. Para Claude Code es .mcp.json en el proyecto:
{
"mcpServers": {
"clewwiki": {
"command": "npx",
"args": ["-y", "@clewwiki/mcp-server"],
"env": {
"CLEWWIKI_URL": "https://wiki.example.com",
"CLEWWIKI_TOKEN": "${CLEWWIKI_TOKEN}"
}
}
}
}Cursor usa el mismo objeto mcpServers en .cursor/mcp.json. Codex lee TOML de ~/.codex/config.toml:
[mcp_servers.clewwiki]
command = "npx"
args = ["-y", "@clewwiki/mcp-server"]
env = { CLEWWIKI_URL = "https://wiki.example.com", CLEWWIKI_TOKEN = "..." }Ese es el transporte stdio: el agente arranca el servidor en la máquina del desarrollador, y el servidor habla con la instancia por HTTPS. Rechaza http:// plano salvo en direcciones locales. Para agentes en CI hay un segundo transporte, streamable HTTP. Viene desactivado por defecto (MCP_HTTP_ENABLED=false) y no admite acceso anónimo.
Lo más fácil es no escribir la configuración a mano: la página Connect an agent de la aplicación imprime el comando exacto para tu cliente y un prompt que explica al agente cómo trabajar con la wiki. Desde la 0.8 también trae comandos cotidianos: leer la wiki antes de una tarea, actualizarla después, abrir una discusión. Para Claude Code hay un comando de una línea que los instala como /wiki-read y /wiki-update.
En qué se diferencia un token de agente de la contraseña de una persona#
El servidor MCP está hecho como un cliente REST corriente de la instancia. Guarda un token y no tiene otra forma de entrar. De ahí sale la propiedad clave: el agente no tiene puertas traseras. Cada llamada pasa por las mismas comprobaciones de permisos, los mismos límites y la misma auditoría que una petición HTTP directa.
Un token está limitado a los espacios a los que se le dio acceso, caduca y se puede revocar. Un token caducado o revocado se rechaza en la autenticación, antes de cualquier escritura. Cada intento de escritura queda en la auditoría dentro de la misma transacción, haya salido bien, haya chocado con el claim de otro o haya llevado un hash obsoleto. Cada token tiene un límite de frecuencia, así que un agente atrapado en un bucle choca con él antes de inundar la wiki.
Hay además un contrato aparte sobre el texto ajeno. Todo lo que una herramienta devuelve del contenido guardado (cuerpos de páginas, notas, nombres, fragmentos de código) va marcado como datos, no como instrucciones. Una página que diga «ignora las instrucciones anteriores» sigue siendo texto. Eso no hace imposible la prompt injection, pero cierra el camino más barato.
Dos agentes en una página#
A este mecanismo le dediqué un artículo entero, así que en breve. Antes de escribir, el agente toma un claim sobre una página o una sección con wiki.claim. La escritura lleva el id del claim y un hash del contenido que el agente leyó. El claim demuestra que nadie más está escribiendo ahora; el hash, que nadie escribió entretanto. Un segundo agente recibe un conflicto con el nombre de quien tiene el claim. Sobrescribir en silencio el texto de otro no es posible. El servidor nunca fusiona por su cuenta: ante un hash obsoleto devuelve ambos hashes y espera a que el agente vuelva a leer la página.
Los claims caducan solos, se pueden renovar (wiki.renew_claim) y liberar (wiki.release_claim). Un administrador puede quitar uno atascado, y eso queda en la auditoría con su propio nombre. Un token de agente no puede liberar a la fuerza el claim de nadie.
Los cambios del agente esperan a una persona sin bloquear#
El agente escribe sin aprobación: su cambio se convierte en la página en el momento en que llega. Si no, el agente esperaría en una cola mientras la persona está ocupada. Pero todo lo que los agentes cambiaron desde la última revisión se acumula en Changes como un diff. Una persona lo acepta o lo revierte, con una nota que el agente leerá antes de su siguiente intento (wiki.get_review).
Los cambios pendientes no se guardan como un flag; se calculan. La versión más reciente que escribió o aceptó una persona es la base, y todo lo que hicieron los agentes después está pendiente.
Quién está ahora en la wiki#
En la 0.8 el panel Presence empezó a mostrar personas además de claims: quién tiene abierta qué página y si la está leyendo o editando. Al lado, los agentes cuyo token hizo peticiones en los últimos diez minutos y la página a la que se refería su última petición. Bajo el título de una página se ve quién más está en ella.
Hay un detalle que me resultó útil antes de lo que esperaba. Un navegador controlado por WebDriver (Playwright, Selenium, Puppeteer) se marca aparte. Es un agente trabajando a través de la sesión de una persona, y a la gente le sirve distinguirlo de un compañero.
El agente obtiene lo mismo de wiki.get_presence, en el campo active_now. Antes de ponerse con una página, ve que alguien está en ella ahora mismo y puede elegir otra tarea en lugar de toparse con un conflicto.
Las tareas vienen del tracker#
Tres herramientas llegaron en la 0.8 junto con la integración de YouTrack y Jira:
wiki.my_tasks: las incidencias sin resolver asignadas a la persona que emitió el token del agente, buscadas en el tracker por su correo.wiki.get_issue: una incidencia por clave, con descripción y comentarios.wiki.search_issues: una búsqueda con consulta de YouTrack o JQL.
Así, «toma mis tareas» en la página Connect an agent se convierte en un flujo real: el agente obtiene la lista, lee una incidencia, encuentra las páginas de la wiki que mencionan su clave y empieza a trabajar ya con contexto. El token del tracker vive solo en el entorno de la instancia y nunca entra en la base de datos.
La limitación, dicha sin rodeos: los clientes de los trackers están probados contra formas de respuesta de API grabadas, todavía no contra un YouTrack o un Jira reales.
Ramas, releases y lo que es fácil olvidar#
La sección Development, que llegó con la 0.9, le sirve más a un agente que a las personas. Lee el repositorio git del espacio y mantiene una línea de trabajo por rama: cuánto va por delante y por detrás de la principal, si está fusionada, a qué release pertenece. El trabajo fusionado sin release se resalta, y una release no puede marcarse como publicada mientras tenga líneas sin fusionar.
Para el agente son tres herramientas (wiki.development, wiki.get_stream, wiki.update_stream) y un parámetro stream_id en wiki.open_discussion. Un agente que se topa con un problema en una rama abre una discusión directamente en la línea de esa rama. Cuando la discusión se resuelve, la decisión se escribe como página en la documentación de la línea y el hilo caduca. Queda la conclusión, no un montón de logs de chat.
Archivos, bandeja de entrada y seguimiento#
El agente puede publicar y leer archivos: wiki.upload_file admite hasta 7 MB a través de la herramienta, los más grandes van por REST con el mismo token; wiki.get_file devuelve el contenido de un archivo de texto de hasta 256 KB. Subir un archivo con un nombre que la página ya tiene añade una versión bajo el mismo enlace.
wiki.watch suscribe a una página o a un espacio, y wiki.check_inbox devuelve lo que le concierne al agente: una respuesta en una discusión que abrió, una mención, la revisión de su cambio, una nueva versión de un archivo. La respuesta encuentra a quien preguntó, sin correo y sin una cola de notificaciones aparte.
Las reglas y las skills viven en la wiki, no en un checkout#
Las reglas del proyecto y las skills reutilizables se guardan en la wiki, y cualquier agente las lee por MCP antes de empezar (wiki.get_rules, wiki.list_skills, wiki.get_skill). Las convenciones del equipo dejan de ser un archivo por herramienta en el portátil de una persona.
Sin embargo, los hosts de agentes cargan las skills desde directorios, y una llamada MCP no puede escribir en disco. Por eso el paquete trae también un comando:
CLEWWIKI_URL=https://wiki.example.com CLEWWIKI_TOKEN=$CLEWWIKI_TOKEN \
npx -y @clewwiki/mcp-server skills install --space MOBILEDescarga las skills del espacio y las escribe en ~/.claude/skills/<slug>/SKILL.md, imprimiendo cada archivo que escribe. --only instala solo las elegidas y --dir escribe en otro directorio.
Y una última cosa contra el «contexto caducado»: una página se puede anclar a una declaración en el código en Swift, TypeScript, TSX o Kotlin. Pasar un formateador no cambia nada, un cambio en el cuerpo marca la página como obsoleta, los renombrados y traslados se reconocen y un borrado se notifica. Cómo funciona, y por qué sin falsos positivos, está en el artículo sobre anclas.
Lo que no prometo#
- Es 0.x. El primer tag salió el 18 de septiembre y el décimo el 5 de octubre. Se añaden herramientas casi en cada release, el agente tiene que reconectarse para verlas y las migraciones de base de datos son frecuentes.
- Los trackers no están probados en real, como ya dije.
- Streamable HTTP viene desactivado. Para agentes en CI hay que activarlo a conciencia y poner la instancia detrás de TLS.
- La auditoría y los claims no protegen del mal contenido. Un agente con permiso de escritura puede escribir disparates con total seguridad. La revisión de cambios existe justo para eso, pero alguien tiene que mirarla.
Pruébalo#
Levanta una instancia con el inicio rápido del README, emite un token para un espacio y pide a un agente que lea la wiki antes de su próxima tarea y la actualice después. Lo que aparezca en Changes te dirá en una tarde si esta forma de trabajar encaja con tu equipo.
La lista completa de herramientas, con sus scopes y errores, está en docs/mcp.md en el repositorio. La visión general del proyecto está en la página de ClewWiki.
