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.

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 cuatro específicas de la app: undo_last_action, save_memory, request_include_context y web_search. En este momento:

Dominio	Herramientas
Notas	`list_notes`, `get_note`, `create_note`, `update_note`, `delete_note`, `summarize_note`, `rewrite_note`
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)
Agendamiento	`get_availability`
UX	`request_approval` (lo usa el agente antes de operaciones masivas)

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.

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.