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 — pídele al asistente del chat de la app que deshaga cualquier acción hecha por MCP
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.
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. Haz clic en cualquier momento para ir directo a Configuración → Herramientas IA (MCP). 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.

Qué puede hacer el cliente de IA

El servidor expone las mismas herramientas que usa el coach integrado, menos cinco específicas de la app: undo_last_action, save_memory, 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`
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`
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), `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)
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.

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.

Trabajar la cola de tareas

El servidor también incluye un prompt, work_queue — en Claude Desktop aparece como el comando /work_queue. Le dice al agente que recoja todas las tareas que hayas entregado en el tablero (el botón destello — mira Entrégale una tarea a tu agente), las trabaje una por una y reporte en las propias tarjetas: un plan mientras trabaja, preguntas como El agente necesita respuesta, resultados como Agente terminó en tu columna Pendiente. 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.

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:

Claude Code — con el servidor añadido (claude mcp add … arriba), una línea de cron o una rutina de Claude trabaja la cola sin supervisión, por ejemplo cada mañana entre semana: claude -p "Load the coachkeeper skill prompt, then run the work_queue prompt". Lo que el agente no pueda decidir aterriza en tu tablero como necesita respuesta, nunca como una suposición.
Cualquier otro agente sin interfaz con un cliente MCP que soporte OAuth funciona igual: apúntalo al servidor, haz que llame al prompt work_queue 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, y todo lo que hace se puede deshacer desde el chat de la app.

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, abre el chat de la app y dile “deshaz eso” — el asistente lo revierte.