Integración MCP

Apunta Claude Code, Cursor, Claude Desktop o cualquier cliente compatible con MCP a tu espacio de CoachKeeper.

Qué es

CoachKeeper expone todo su set de herramientas de agente sobre el Model Context Protocol (MCP) — el estándar abierto que los clientes de IA usan para hablar con herramientas externas. Cualquier cliente compatible con MCP puede leer, buscar, crear, actualizar y agendar en tu espacio igual que el coach integrado.

Mismas reglas en ambos lados:

Misma autenticación — inicio de sesión OAuth con tu cuenta de CoachKeeper, nunca un secreto pegado a mano
Mismo registro de acciones — cada creación / actualización / eliminación queda en el mismo registro que usa el coach integrado
Mismo deshacer — cada acción hecha por MCP se puede deshacer desde su línea en Hoy o en el registro de acciones, y deshacer nunca pisa una edición que hiciste después del agente
Misma disponibilidad — las ventanas semanales se respetan al agendar

Por qué usarlo

Ya vives en Cursor o Claude Code. Deja que el editor convierta un comentario TODO en una tarea real de tu backlog sin salir del IDE.
Usas Claude Desktop a diario. Pídele que agende tu semana usando tu backlog y tu disponibilidad — sin copiar y pegar.
Construyes tu propio agente. Trata a CoachKeeper como un servicio PKM gestionado al que puede llamar.

Conectar un cliente

No hay nada que generar, copiar ni pegar. CoachKeeper implementa la especificación de autorización de MCP (OAuth 2.1): le das a tu cliente la URL del servidor y, la primera vez que se conecta, tu navegador abre una pantalla de consentimiento de CoachKeeper. Inicia sesión (si no lo estás ya), pulsa Autorizar y listo — a partir de ahí el cliente renueva su acceso solo. Es el mismo flujo que usan GitHub, Linear, Notion y Sentry para sus servidores MCP.

Claude Code (CLI)

claude mcp add --transport http coachkeeper https://api.coachkeeper.com/api/v1/mcp

Verifica con claude mcp list. En el primer uso abrirá tu navegador para autorizar.

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coachkeeper": {
      "type": "http",
      "url": "https://api.coachkeeper.com/api/v1/mcp"
    }
  }
}

Reinicia Claude Desktop. Busca el icono 🔌 en la barra de entrada — debe listar coachkeeper y pedirte autenticarte.

Cursor

Settings → MCP → Add new MCP server, pega el mismo snippet JSON.

Cualquier otro cliente MCP

El mismo JSON. Dos cosas importan: type: "http" y la URL. Sin cabeceras — el cliente descubre los endpoints OAuth automáticamente y te guía por el consentimiento. Eso sí, el cliente tiene que soportar OAuth para MCP: los harness cuyo cliente MCP solo acepta cabeceras estáticas (DeepSeek Harness, al momento de escribir esto) todavía no pueden iniciar sesión.

Enséñale a tu agente

Conectar le da a tu agente las herramientas; enseñarle el estilo de la casa lo hace bueno usándolas. Configuración → Herramientas IA (MCP) incluye un briefing breve que puedes copiar — las entidades y cómo se relacionan, cómo buscar sin desperdiciar llamadas antes de listar todo, cómo se formatean las notas y las tareas, y qué debe confirmar contigo antes de cambiar algo.

Claude Code: descárgalo como SKILL.md y guárdalo en ~/.claude/skills/coachkeeper/ — se carga automáticamente cada vez que trabajes con CoachKeeper. Solo lo haces una vez: cuando el skill cambia, tu agente ve que su copia está desactualizada y te pregunta si la actualiza por ti.
Claude Desktop / ChatGPT / Cursor y otros: pégalo en las instrucciones personalizadas o de proyecto del agente.

El servidor ya envía una versión compacta de este briefing a cada cliente al conectarse, y además sirve el briefing completo por el propio MCP — como el prompt skill (un comando de barra en Claude Desktop) y como el recurso coachkeeper://skill. Un cliente que muestre prompts lo carga con un clic, sin pegar nada; instalar el archivo SKILL.md sigue valiendo la pena si usas un mismo agente con CoachKeeper con regularidad, para que esté ahí antes de la primera llamada.

Estado de la conexión de un vistazo

Una vez que un cliente está conectado, un pequeño ícono de enchufe/agente en la barra superior de la app se convierte en una insignia de estado — ámbar cuando está inactivo, verde brevemente cada vez que el agente hace un cambio. Un pequeño número en su esquina cuenta lo que espera tu decisión: una tarea sobre la que el agente preguntó, una tarea terminada para revisar o una nota cambiada en dos sitios mientras estabas sin conexión. Haz clic en el ícono para ver esa lista y la conexión, con Configuración a un clic. Antes de conectar algo, el panel de chat también muestra una tarjeta única de “trae tu propio agente” que apunta al mismo flujo de configuración.

Gestionar el acceso

Configuración → Herramientas IA (MCP) lista cada cliente conectado a tu cuenta, con la fecha de conexión y el último uso. Revocar corta el acceso de inmediato — el cliente tendría que pasar de nuevo por el consentimiento en el navegador para reconectarse.

Por debajo, cada autorización emite un token de acceso de corta vida más un token de renovación rotatorio. Una conexión sin uso durante más de 7 días expira sola; los clientes activos se renuevan en silencio y permanecen conectados indefinidamente.

Elige qué puede ver cada agente

Quizá no quieras que todos los agentes lo lean todo: un agente de programación no tiene nada que hacer en tu diario. Cada agente puede tener sus propias reglas, por etiquetas y cuadernos:

Leer o Leer y escribir en algunas etiquetas o cuadernos limita al agente a ellos (subetiquetas incluidas). Solo cambia lo que está bajo Leer y escribir.
Ocultar aparta de él una etiqueta o un cuaderno, y gana a todo lo demás: «todo menos mi diario».
Sin reglas (— en todo) significa acceso completo, como antes.

Lo que queda fuera de las reglas de un agente no existe para él: no lo encuentra en búsquedas, listas, el resumen del espacio de trabajo ni en la lectura de fondo del chat, y una escritura ahí se rechaza. Define las reglas en la pantalla de consentimiento al autorizar un agente nuevo (el bloque opcional para limitar lo que puede ver), o más tarde en Ajustes → Ajustes del agente → Qué puede ver cada agente, que lista el chat de la app y cada agente que conectaste.

Una memoria para todos los agentes

Cada asistente guarda su propia memoria sobre ti, y nada de eso viaja. CoachKeeper guarda en su lugar un solo texto Sobre mí. Está en Ajustes → Ajustes del agente → Sobre mí: escríbelo tú, en texto plano, y guárdalo. Todos los agentes conectados lo leen primero y añaden ahí lo que aprenden. Cada cambio de un agente va firmado con su nombre y aparece en Hoy, donde Deshacer lo revierte.

Importar la memoria de otro asistente toma la memoria que Claude o ChatGPT guardan sobre ti (pégala ahí) y se la pasa como tarea a tu propio agente conectado. El agente propone añadidos a Sobre mí como una ejecución que revisas: Descartar los quita. Todos los agentes pueden leer Sobre mí y añadir cosas, sea cual sea lo que les dejes ver.

Un segundo agente empieza donde lo dejó el primero. Un agente conectado puede pedir el relevo (get_handoff): lo que otros agentes cambiaron y preguntaron desde su última visita, las preguntas que esperan tu respuesta y lo que editaste tú.

Qué puede hacer el cliente de IA

El servidor expone las mismas herramientas que usa el coach integrado, menos cuatro específicas de la app: undo_last_action, request_include_context, request_approval (tu propio agente maneja sus propias aprobaciones) y web_search. En este momento:

Dominio	Herramientas
Notas	`list_notes`, `get_note`, `create_note`, `update_note`, `delete_note`, `summarize_note`, `rewrite_note`, `graft_notes` (fusiona dos notas que dicen lo mismo — un solo deshacer lo revierte; una nota perenne no se puede fusionar en otra)
Historial y enlaces	`get_note_history` (las versiones anteriores de una nota y quién reemplazó cada una), `get_backlinks` (qué enlaza con un elemento), `get_related` (elementos parecidos)
Enlaces guardados	`list_links`, `save_link`, `update_link`, `delete_link`
Papelera	`list_trash`, `restore_item`
Relevo y jardín	`get_handoff` (qué cambió desde la última visita de este agente), `lint_garden` (duplicados, enlaces rotos, elementos sin archivar, líneas viejas en Sobre mí, etiquetas que se solapan — como propuestas), `set_recall_prompt` (escribe la pregunta de repaso que Hoy hace sobre una nota)
Sobre mí	`add_to_about_me` (añade una línea), `set_about_me` (reescribe el texto, cuando tú lo pides) — el texto llega con `get_workspace_overview`
Búsquedas guardadas	`list_saved_searches`, `run_saved_search`
Cuadernos	`list_notebooks`, `get_notebook` (el índice, o el libro entero en markdown), `create_notebook`, `update_notebook`, `delete_notebook`
Tareas	`list_todos`, `get_todo`, `create_todo`, `update_todo`, `delete_todo`, `complete_recurring_todo`
Ejecuciones del agente	`list_agent_tasks`, `claim_todo`, `report_run`, `accept_run`, `revise_run`, `discard_run`, `evidence_upload`, `settle_git`
Eventos	`list_events`, `get_event`, `create_event`, `update_event`, `delete_event`
Fuentes	`list_sources`, `get_source_content`, `search_sources` (RAG)
Búsqueda	`search_items` (cualquier entidad, por título o contenido, con los mismos filtros de búsqueda que la app — `tag:`, `is:todo`, `before:`…), `semantic_search` (por significado, no solo coincidencia de palabras)
Etiquetas	`list_tags` (todas las etiquetas con contadores en vivo), `get_tag_dossier` (el mapa de una etiqueta: un boceto de conceptos en mermaid de lo archivado bajo ella más notas breves de estado, cada una apuntando a ids reales — el mismo mapa que muestra la página de la Biblioteca, incluida cualquier ordenación que hayas hecho a mano, que un cliente tiene indicado no redibujar), `update_tag` (renombrar, recolorear o describir una etiqueta — el nuevo nombre llega a todo lo archivado bajo ella), `merge_tags` (fusionar una etiqueta en otra), `delete_tag` (los elementos se conservan y pierden la etiqueta; si la etiqueta aún tiene elementos se rechaza hasta que el cliente confirme con `untag_items`)
Orientación	`get_workspace_overview` (una instantánea de tu espacio de trabajo — contadores, actividad reciente — para que un cliente se ubique antes de empezar)
Agendamiento	`get_availability`

Notas, tareas y fuentes se devuelven como markdown bien formateado, no como bloques JSON en bruto. Sus herramientas de listado (list_notes, list_todos, list_sources) están paginadas y admiten filtros — por estado, etiqueta, cuaderno, ventana de vencimiento o título — en vez de un tope fijo de filas, así un cliente puede recorrer un espacio de trabajo grande sin perder elementos. Las notas ahora se pueden etiquetar igual que ya podían las tareas y los eventos.

Una tarea lleva dos fechas independientes, y las herramientas las mantienen separadas: due_date es la fecha de entrega, y scheduled_start / scheduled_end es el tiempo reservado para hacer el trabajo — que es lo que muestra tu calendario. Reservar tiempo significa agendar la tarea misma; un agente nunca debería crear un evento que represente una tarea. list_todos filtra por cualquiera de las dos (due_before / due_after, scheduled_from / scheduled_to) y acepta unscheduled: true para encontrar trabajo que aún necesita un hueco.

Dos convenciones de escritura que vale la pena enseñar a tu agente: un bloque de código ```mermaid en cualquier nota se renderiza como diagrama en vivo dentro de la app, y el material rico de una tarea — briefs, investigación, diagramas — va en una nota vinculada mediante context_note_ids, que es lo que muestra la página de la tarea.

Las notas son más ricas que el markdown simple, y los agentes escriben las mismas formas que tú: ==marcador==, destacados (> [!note] Título), bloques ::: columns y ::: margin, $matemáticas$ , bloques vivos ```html y ![nombre](source:<id>) para mostrar un archivo abierto en la página. Una nota también puede llevar un marco de página — update_note(frame="folio") — y list_frames, get_frame y save_frame permiten a un agente leer los diseños y crear otros nuevos. El contrato completo está en docs/note-dialect.md del repositorio.

Cada herramienta devuelve la misma forma que una llamada normal a la API y genera la misma entrada en el registro de acciones. Para la lista viva y autoritativa, llama a tools/list (estándar MCP) desde tu cliente.

Cuida el jardín

Pide a un agente conectado que revise tu jardín, o usa su prompt Tend the garden (lint_garden). Encuentra duplicados, enlaces rotos, notas y tareas sin archivar, líneas desactualizadas en Sobre mí y etiquetas que se solapan, y propone un arreglo para cada cosa. Solo cambia lo que apruebas, con las herramientas normales, así que cada cambio aparece en Hoy con Deshacer. Un agente con reglas solo revisa lo que puede ver.

Trabajar tus tareas del agente

Las tareas que entregas en el tablero (la columna Agente — mira Entrégale una tarea a tu agente) se trabajan desde tu propio agente, cuando tú lo dices. El servidor incluye tres prompts para ello — comandos en Claude Code (/mcp__coachkeeper__<nombre>) y prompts en Claude Desktop:

agent_tasks — My agent tasks: lista lo que te necesita, lo que está en cola, lo que está en marcha y lo que espera tu revisión, y te deja elegir: trabajar una, trabajar hasta tres, responder una pregunta, aceptar, revisar o descartar. Con la skill de CoachKeeper instalada en Claude Code, /coachkeeper hace lo mismo.
work_task — trabaja una tarea, por id o por título.
work_queue — trabaja la cola, de la más antigua a la más reciente, hasta tres.

Cada tarea se trabaja como una ejecución: el agente la reclama (claim_todo — así dos agentes nunca toman la misma tarea), trabaja y reporta (report_run — terminada con un resumen, o necesita respuesta con sus preguntas). Todo lo que escribe en CoachKeeper entre medias pertenece a esa ejecución, así que la tarjeta muestra exactamente qué cambió y Descartar puede deshacerlo de una vez. accept_run, revise_run y discard_run son decisiones tuyas, que el agente transmite cuando tú lo dices — se le indica que liste lo que deshará un descarte y espere tu sí. No hay un hilo de chat que mantener vivo — la tarea es el hilo — así que una pregunta que respondes el martes puede recogerla otra sesión del agente el jueves.

Si una etiqueta tiene una carpeta del agente (un nombre, p. ej. coachkeeper — nunca una ruta completa), sus tareas la llevan, y un agente con acceso a archivos trabaja solo dentro de ella. En un repositorio git nunca toca tus archivos abiertos ni lo que no has guardado, y nunca sube nada: el cambio de cada tarea espera aparte hasta que decidas. Si una tarea necesita pruebas o una compilación, el agente las ejecuta en una copia aparte que limpia antes de informar. La tarjeta muestra qué cambió en palabras sencillas, con los detalles técnicos plegados bajo Detalles. Si la carpeta no está en el ordenador actual, la tarea se salta y espera a la máquina que la tiene. La carpeta también puede contener varios repositorios — un proyecto con un repo api y otro web, por ejemplo: el agente trabaja en los repositorios que la tarea necesite (y pregunta si no lo tiene claro). En una carpeta que no es un repositorio git, el agente escribe los archivos directamente y te avisa antes de que Descartar no puede deshacerlos.

Aceptar lo añade a tu proyecto. Descartar es como si nunca hubiera pasado. Tu agente aplica la decisión la próxima vez que se ejecute en ese ordenador — una línea, sin preguntas. Si tus cambios posteriores lo impiden, la tarea vuelve a tu revisión diciendo por qué, y Revisar hace que el agente lo rehaga encima. En Claude Code, una sola regla de permisos deja que estos pasos se ejecuten sin preguntar cada vez: Bash(sh .git/ck:*). El push nunca se incluye.

Pruebas. Cada informe muestra antes → después — hasta tres pruebas, la más clara primero: las pruebas antes y después, la línea clave que cambió o capturas de pantalla. Las capturas van del terminal del agente a un enlace de subida temporal (evidence_upload), nunca por su contexto. Si una ejecución no puede mostrar pruebas, dice por qué.

Ejecutar la cola con un horario

CoachKeeper nunca arranca un agente por sí mismo; las tareas en cola esperan a que pase un cliente. Si quieres que eso ocurra sin ti, programa el cliente. En Configuración → Herramientas IA (MCP) → Pon la cola en horario están las instrucciones que debes darle — el servidor sirve el mismo texto como el prompt queue_routine y el recurso coachkeeper://queue-routine. Son work_queue hecho seguro para una ejecución que nadie está mirando:

Se detiene al instante si la cola está vacía, sin cambiar nada — así que un horario frecuente no cuesta casi nada.
Pocas tareas por ejecución, la más antigua primero, una por una. Una tarea que una ejecución anterior dejó a medias se retoma pasada una hora.
Nunca pregunta al vacío. Lo que no pueda decidir se convierte en El agente necesita respuesta en la tarjeta, con la pregunta escrita en la tarea. Respóndela en la tarea o desde Hoy, y la siguiente ejecución continúa donde se quedó.
Cada resultado es una nota de una página: una nota nueva enlazada a la tarea y archivada bajo su etiqueta — primero la respuesta, luego lo que encontró o hizo, un diagrama o una tabla solo cuando el contenido lo pide, próximos pasos y fuentes. La tarea espera en tu columna Agente para que la revises.

Dónde programarlo:

Claude Desktop, en tu propio ordenador — pestaña Code → Routines → New routine → Local. Pega las instrucciones, elige como carpeta de trabajo la que contiene tus proyectos y escoge un horario. Pulsa Run now una vez y elige Always allow para cada herramienta de CoachKeeper que pregunte; las siguientes ejecuciones pasarán sin detenerse. Una rutina local solo se dispara con la app abierta y el ordenador despierto — tras el reposo se pone al día con una sola ejecución.
Claude Code — con el servidor añadido (claude mcp add … arriba), una línea de cron o launchd ejecutada desde tu carpeta de proyectos: claude -p "Run the queue_routine prompt from the coachkeeper server".
Claude en la nube — una rutina en la nube en claude.ai/code/routines con el conector de CoachKeeper funciona con el portátil cerrado, como máximo cada hora. Puede investigar y escribir; no llega a los archivos de tu ordenador.
ChatGPT — una tarea programada con el conector de CoachKeeper y las mismas instrucciones. Solo investigación y escritura.
Cualquier otro agente sin interfaz con un cliente MCP que soporte OAuth funciona igual: apúntalo al servidor, haz que cargue el prompt queue_routine y ejecútalo con el temporizador que quieras.

Las salvaguardas siguen aplicando: el agente solo puede hacer lo que haría una persona con tu cuenta. Lo que hizo mientras no estabas aparece en Hoy, donde cada línea se puede comparar o deshacer.

Cosas que saber

HTTP streamable, sin estado. No hay conexión persistente — cada petición lleva un bearer token de corta vida que el cliente gestiona por ti.
Hoy no hay límite de tasa por petición. Las llamadas de herramientas MCP están exentas del limitador de tasa de la web. Sé un buen ciudadano — podrían introducirse límites razonables más adelante.
Tokens estáticos antiguos (de antes de OAuth) siguen funcionando hasta que expiren, pero ya no se pueden generar nuevos. Reconecta con OAuth — es menos trabajo y nunca muere en silencio.
¿CoachKeeper auto-hospedado? Mismo protocolo: apunta a tu propio https://tu-host/api/v1/mcp.

Resolución de problemas

Síntoma	Causa probable
El cliente dice que el servidor no responde	URL incorrecta — debe terminar en `/api/v1/mcp` (no `/mcp`)
El consentimiento en el navegador nunca se abre	Tu cliente es anterior al soporte OAuth de MCP — actualízalo
`401 Unauthorized` en cada llamada	La conexión fue revocada o expiró por inactividad — reconecta (el cliente volverá a abrir el consentimiento)
Las llamadas funcionan pero nada aparece en la app	Autorizaste con otra cuenta de CoachKeeper — revoca en Configuración y reconecta con la correcta
El cliente no lista herramientas	Servidor accesible pero aún sin autorizar — dispara el flujo de autenticación (p. ej. `/mcp` en Claude Code)

Dónde ves lo que hizo

Los cambios hechos por MCP se empujan a tus vistas abiertas de CoachKeeper en tiempo real — una tarea creada desde Cursor aparece en tu tablero Kanban al instante, sin recargar. Cada acción queda además en el mismo registro de acciones que usa el coach integrado, así que si un cliente externo hizo algo que no querías, pulsa Deshacer en su línea de Hoy — o abre el chat de la app y dile “deshaz eso”.