Referencia de herramientas MCP

El servidor MCP de Becoming expone 20 herramientas — 12 para leer tu biblioteca y áreas de interés, y 8 para tomar acción: agregar subrayados y fuentes a tu biblioteca y actuar en La Academia — además de varios recursos para clientes de IA compatibles con MCP.

Las herramientas de lectura necesitan el permiso :read correspondiente. Las de escritura necesitan el permiso :write correspondiente y requieren que el cliente confirme cada acción (mira Herramientas de escritura más abajo).

Si aún no has conectado un cliente, mira Conectar un cliente MCP.

Herramientas de lectura

search_highlights

Busca subrayados en la biblioteca del usuario usando recuperación de texto completo, semántica (vectorial) o híbrida. Híbrida es el modo por defecto y combina ambas señales mediante fusión por rango recíproco; vuelve a texto completo cuando no hay un embedding disponible para la consulta.

Permiso requerido: highlights:read

Entradas:

Campo	Tipo	Notas
query	string (requerido)	Texto de búsqueda.
mode	fulltext | semantic | hybrid	Por defecto hybrid.
source_id	integer	Limitar a subrayados de una fuente.
limit	integer (1–50)	Tamaño de página. Por defecto 10.
cursor	string	Valor meta.next_cursor de la respuesta anterior.

Devuelve: subrayados que coinciden con contenido, ubicación, metadata de la fuente, conteo de notas y metadata de paginación.

list_sources

Lista las fuentes en la biblioteca del usuario.

Permiso requerido: sources:read

Entradas:

Campo	Tipo	Notas
q	string	Búsqueda opcional por título/autor.
type	Book | Article | Video | Podcast	Filtro opcional.
limit	integer (1–50)	Tamaño de página. Por defecto 20.
cursor	string	Valor meta.next_cursor de la respuesta anterior.

Devuelve: fuentes con título, tipo, autor, URL de portada y conteos de subrayados por fuente.

get_source

Obtiene una fuente individual y los subrayados que el usuario tiene asociados.

Permiso requerido: sources:read

Entradas:

Campo	Tipo	Notas
id	integer (requerido)	Id de la fuente.

Devuelve: metadata de la fuente más los subrayados del usuario para esa fuente.

get_highlight

Obtiene un subrayado individual con la metadata de su fuente.

Permiso requerido: highlights:read

Entradas:

Campo	Tipo	Notas
id	integer (requerido)	Id del subrayado.

Devuelve: contenido del subrayado, ubicación, metadata de la fuente y el conteo de notas del usuario para ese subrayado.

get_import

Consulta el estado de una importación iniciada por add_source. Las importaciones corren en segundo plano; cuando una termina, confirma la nueva fuente con list_sources.

Permiso requerido: sources:read

Entradas:

Campo	Tipo	Notas
id	integer (requerido)	El import_id que devolvió add_source.

Devuelve: el estado de la importación (pending | processing | completed | failed), sus conteos de resultado y el motivo de falla cuando falló.

Ten en cuenta que, si a un video se le acabaron los créditos, el barrido nocturno lo retoma como una importación nueva: el import_id original conserva para siempre su resultado de créditos agotados, así que volver a consultarlo reporta un video truncado mucho después de que ya se subrayó el resto. En su lugar, sigue el highlights_count de la fuente con list_sources o get_source: sube a medida que el barrido va procesando fragmentos. Ninguno de los dos es un indicador de finalización, así que espera un conteo que sube, no un estado terminal.

Áreas de interés y prácticas (lectura)

Estas herramientas leen tus datos de La Academia. get_academy_status no necesita permiso — un cliente puede llamarla para comprobar si las herramientas de áreas de interés y prácticas están disponibles antes de usarlas.

Herramienta	Propósito	Entradas	Permiso requerido
get_academy_status	Comprobar el acceso a La Academia y la disponibilidad de áreas de interés y prácticas	Ninguna	Ninguno
list_themes	Listar las áreas de interés del usuario, activas y pasadas	Ninguna	themes:read
get_theme_timeline	Obtener una semana de la línea de tiempo de prácticas de un área de interés, alrededor de una fecha	theme_id (requerido); date (fecha ISO opcional, por defecto hoy)	themes:read
get_theme_generation	Consultar el estado y resultado de una generación de área de interés	id (requerido)	themes:read
list_theme_practices	Listar las prácticas de un área de interés	theme_id (requerido)	practices:read
get_today_practices	Obtener las prácticas de hoy	Ninguna	practices:read
get_practice_reflection	Leer una reflexión guardada de una práctica	practice_id (requerido)	reflections:read

Herramientas de escritura

Las herramientas de escritura modifican datos en tu biblioteca, así que llevan una protección adicional. Cada una requiere el permiso :write correspondiente, y el cliente debe enviar confirm: true junto con una breve cadena user_intent que describa lo que pediste. Si falta cualquiera de los dos, la llamada se rechaza — nada se escribe por accidente.

add_highlights y add_source funcionan en cualquier plan; las herramientas de escritura de áreas de interés, prácticas y reflexiones están disponibles solo en La Academia.

Cada herramienta de escritura recibe confirm: true y user_intent además de las entradas específicas que se indican abajo.

Herramienta	Propósito	Entradas	Permiso requerido
add_highlights	Guardar hasta 20 pasajes como subrayados — en una fuente existente de tu biblioteca, o en un libro o artículo encontrado o creado a partir de metadatos	source_id o source (type Book | Article; title; author requerido para libros; url requerida para artículos; language opcional); highlights (arreglo de content con location y timestamp_seconds opcionales)	highlights:write
add_source	Agregar una fuente sin subrayados — un enlace (los videos de YouTube importan su transcripción; otras páginas se descargan y guardan como artículos legibles) o un libro	url o book (title + author, language opcional). Asíncrona: consulta el import_id devuelto con get_import	sources:write
start_theme_generation	Iniciar la generación de una nueva área de interés desde tu biblioteca, un subrayado o una intención	intent (opcional, máx. 280 caracteres); seed_highlight_id (opcional)	themes:write
generate_theme_practices	Generar las prácticas diarias de un área de interés	theme_id (requerido); context (work | personal | both, requerido); mix (act | reflect | balanced, requerido)	practices:write
complete_theme	Finalizar un área de interés	theme_id (requerido)	themes:write
complete_practice	Marcar una práctica como hecha	practice_id (requerido)	practices:write
skip_practice	Omitir una práctica	practice_id (requerido)	practices:write
log_practice_reflection	Guardar una reflexión de una práctica de reflexión	practice_id (requerido); body (requerido, no vacío)	reflections:write

Créditos de IA

Dos de estas herramientas gastan créditos de IA de la misma asignación que usan las apps:

• add_source con un url: Becoming trae la página y la lee por ti, lo que cuesta 1 crédito para una página web, o 1 por cada ~15 minutos de transcripción en un video de YouTube. Agregar un libro no cuesta nada.
• start_theme_generation: 66 créditos desde toda tu biblioteca, o 10 desde un seed_highlight_id o un intent. Las prácticas van incluidas, así que generate_theme_practices no cuesta nada aparte.

Todo lo demás de esta lista, incluido add_highlights, es gratis. Sin créditos, add_source igual guarda la fuente; lo único que espera es el subrayado.

Recursos

Los recursos son URIs estables que un cliente MCP puede leer cuando los necesita. Becoming expone tanto URIs de colección (que devuelven una lista) como plantillas por elemento.

URI	Devuelve	Permiso
becoming://highlights	Colección de subrayados recientes	highlights:read
becoming://highlights/{id}	Un subrayado individual	highlights:read
becoming://sources	Colección de fuentes	sources:read
becoming://sources/{id}	Una fuente con sus subrayados	sources:read
becoming://notes	Colección de notas	notes:read
becoming://notes/{id}	Una nota individual	notes:read

Permisos

Hay once permisos disponibles; los otorgas en la pantalla de autorización al conectar un cliente. get_academy_status no necesita permiso.

Permiso	Permite
highlights:read	search_highlights, get_highlight, recursos de subrayados
highlights:write	add_highlights
sources:read	list_sources, get_source, get_import, recursos de fuentes
sources:write	add_source
notes:read	Colección de notas y recursos por nota
themes:read	list_themes, get_theme_timeline, get_theme_generation
themes:write	start_theme_generation, complete_theme
practices:read	list_theme_practices, get_today_practices
practices:write	generate_theme_practices, complete_practice, skip_practice
reflections:read	get_practice_reflection
reflections:write	log_practice_reflection

Otorgar menos permisos está bien — las herramientas o recursos que requieran permisos no otorgados simplemente devolverán un error de permiso. Los permisos de escritura de áreas de interés, prácticas y reflexiones aplican en La Academia; highlights:write y sources:write funcionan en cualquier plan.

Errores

El servidor MCP usa códigos de error estándar de JSON-RPC para fallos a nivel de protocolo y errores en el resultado de la herramienta para fallos a nivel de aplicación. Códigos relevantes:

Código	Significado
-32001	Autenticación requerida (token inválido, expirado o revocado).
-32002	Permiso insuficiente o suscripción requerida.
-32003	Recurso no encontrado.
-32004	Límite de tasa alcanzado; espera y reintenta.
-32010	Se requiere una suscripción a La Academia para esta herramienta.
-32011	Entrada inválida — por ejemplo, una herramienta de escritura llamada sin confirm: true y user_intent, o un fallo de validación.
-32099	Fallo inesperado del backend; reintenta más tarde.

Hay límites de tasa por conexión. La mayoría de los clientes manejan la espera automáticamente.

Paginación

search_highlights y list_sources usan paginación basada en cursor. Pasa el valor meta.next_cursor de la respuesta anterior como entrada cursor en la siguiente llamada. Continúa hasta que next_cursor sea null.