Un RAG agéntico servido como trece herramientas MCP
Cuando conectas un modelo a tus datos, la primera tentativa siempre es la misma: meter el contexto en el prompt. Un volcado de la documentación, las últimas filas de la tabla, el resumen que generaste anoche. Funciona con un corpus pequeño y deja de funcionar en cuanto crece, porque el contexto es finito y porque el modelo no sabe qué le falta.
La alternativa es no darle contenido, sino la capacidad de ir a buscarlo. Eso es un servidor MCP: un proceso que expone herramientas —funciones con nombre, argumentos tipados y una descripción— para que el agente decida cuál llamar y con qué. El protocolo lo estandariza; lo interesante no es el protocolo, sino qué decides exponer.
Una herramienta no es un endpoint
La diferencia parece de matiz y no lo es. Un endpoint lo llama un programa que ya sabe lo que quiere; una herramienta la elige un modelo a partir de su descripción. Eso cambia el diseño: el nombre importa, la descripción importa, y los argumentos tienen que ser evidentes para alguien que no ha leído tu código.
También cambia qué NO expones. Dar acceso directo a la base de datos parece lo más flexible, y es precisamente lo que peor funciona.
Una herramienta bien definida es una decisión tomada de antemano: este es el orden en que se buscan las cosas, este es el límite, así se citan las fuentes. El modelo no tiene que reinventarlo en cada llamada.
Las trece del portal
El servidor MCP de Zetesis Portal expone trece herramientas sobre el contenido indexado. No son trece formas de hacer lo mismo: cubren tres momentos distintos de una consulta.
| Momento | Herramientas |
|---|---|
| Orientarse | list_retrieval_profiles, get_taxonomy_tree, get_filter_criteria, get_collection_stats |
| Buscar | search_collections, get_post_summaries, get_book_toc |
| Leer | get_chunks_by_ids, get_chunks_by_parent |
| Sintetizar | summarize_document, extract_claims, compare_perspectives, synthesize_comparison |
El grupo de orientarse es el que más se subestima. Un agente que empieza preguntando qué taxonomías existen acierta mucho más que uno que dispara una búsqueda a ciegas, porque puede filtrar por autor en vez de meter el nombre del autor en la consulta —que en un corpus de citas textuales no aparece nunca, porque nadie se cita a sí mismo por su apellido—.
- list_retrieval_profilesqué puedo leer
- get_taxonomy_treecómo se filtra
- search_collectionsconcepto, no palabras
- get_chunks_by_idsel texto entero
- extract_claimscon su fuente
Qué hace por dentro search_collections
De las trece, la que más se usa es la de buscar, y conviene saber qué hace porque tiene tres modos y fallan en sitios distintos.
El léxico busca las palabras que escribiste. Es exacto y explicable: si un resultado sale, sabes por qué. Su límite es que une los términos con Y —una consulta de cuatro palabras exige las cuatro en el mismo fragmento— y que no sabe nada de sinónimos.
El semántico busca por significado a través de embeddings. Encuentra lo que querías decir aunque no coincida ni una palabra, y a cambio no distingue bien entre parecido y correcto.
| Modo | Acierta cuando | Falla cuando |
|---|---|---|
| Léxico | Sabes el término exacto | La consulta es larga o hay sinónimos |
| Semántico | Describes la idea | Hay que distinguir entre parecidos |
| Híbrido | No sabes cuál de los dos casos es | Hay que explicar por qué salió algo |
El total de resultados miente en modo vectorial
Es la trampa que más veces me ha mordido. En los modos con vectores, el recall no lo marca la página que pides: el motor recupera un número fijo de vecinos y pagina sobre ellos. El total que devuelve está acotado por ese número, no por lo que hay en el corpus.
Así que preguntarle al agente «¿cuánto contenido tengo sobre esto?» en modo semántico devuelve algo que parece un dato y no lo es. Para contar de verdad hay que repetir la consulta en léxico y mirar ese total.
Esto es también lo que separa una herramienta de un endpoint: la descripción de search_collections tiene que enseñar al modelo a consultar por concepto y a filtrar por taxonomía, porque un agente que mete el nombre del autor en el texto de la consulta no encuentra nada —en un corpus de citas nadie se nombra a sí mismo por su apellido—.
El peso entre la parte léxica y la semántica en el modo híbrido lo llevo por intuición y por pruebas manuales, no por una medida. Sé que funciona mejor que cualquiera de los dos por separado; no sé cuál es el punto óptimo ni si cambia según el corpus.
Por qué el semántico falla en silencio
Hay un motivo concreto detrás de que el modo vectorial deje fuera cosas que sí están, y no es del corpus: es geométrico. En espacios de muchas dimensiones aparecen puntos que quedan cerca de casi todo lo demás. Se llaman hubs.
Una entrada genérica acaba colocada en mitad de la nube y gana comparaciones que no debería ganar, no porque encaje mejor, sino porque está cerca de todo. Si el agente ordena por coseno y se queda con los primeros, la cola larga no aparece nunca.
La corrección habitual penaliza a los puntos que son vecinos de demasiadas cosas. Reordena bien, pero deforma la escala, así que su número deja de significar nada por sí solo: para decidir si un resultado es fiable hay que mirar la similitud cruda, no la corregida.
Y la confianza tampoco sirve para eso. Un softmax sobre las finalistas mide cuánto destaca la primera sobre las demás, no si la primera es buena. Cinco candidatas malas y parecidas dan confianza baja; cinco malas donde una destaca, alta. Ninguna de las dos dice si acertaste.
Trocear sin perder la cabecera
Un documento largo no cabe en una llamada de embedding, y la manera de recomponerlo cambia lo que la herramienta devuelve. Promediar los trozos a partes iguales trata igual la primera página que la lista de firmas del final.
Con peso decreciente —el primer trozo pesa más que el segundo, y así— el vector resultante se parece más a lo que el documento dice que es. La cabecera de un acta informa mucho más sobre su naturaleza que su última página.
Perfiles: qué puede leer cada agente
Un servidor de herramientas sin control de alcance es un problema de seguridad con buena documentación. En el portal, cada agente tiene asignados perfiles de recuperación que definen el alcance duro de lo que puede leer: qué colecciones, qué autores, qué carpetas.
El detalle que importa es la dirección. Los filtros que pasa el agente en cada llamada solo pueden acotar dentro de ese alcance, nunca ampliarlo. Si pide un autor que su perfil no cubre, la petición no falla en silencio ni le devuelve resultados de más: se descarta el filtro y la respuesta lleva un aviso explicando por qué. El agente puede corregir; lo que no puede es salirse.
El mismo servidor, distinto alcance
Sobre esa base, los tokens de búsqueda se emiten por usuario y llevan sus propios perfiles. Dos personas de organizaciones distintas apuntan al mismo servidor y ven corpus distintos, sin desplegar nada por cliente.
Eso abre una posibilidad que no había previsto al empezar: cualquier cliente MCP externo —Claude Desktop, Cursor— puede consultar el portal con esas credenciales. El buscador deja de estar solo dentro de la web y pasa a estar donde la gente ya trabaja.
El mismo patrón, otro dominio
En Konect, el servidor MCP no expone documentos sino búsqueda, facetas, agregaciones y gráficos sobre conversaciones analizadas. Un chat embebido las usa para responder preguntas sobre los datos. Cambia el dominio entero y la forma se mantiene: herramientas con alcance definido en vez de un volcado al prompt.
Y en la consultoría de desarrollo agéntico son servidores a medida contra Loki, Grafana o GitHub. El agente vive dentro del sistema, con las mismas herramientas que tendría yo.
Lo que sigue abierto
Trece herramientas ya son bastantes para que el modelo se equivoque eligiendo. No tengo medida de con qué frecuencia coge la que no toca, y es lo siguiente que quiero instrumentar: no la calidad de la respuesta, sino la calidad de la elección.
Tampoco tengo claro dónde está el techo. Sospecho que el límite no es cuántas herramientas expones sino cuánto se solapan entre ellas, y eso no lo sé medir todavía.
Plugins de Payload y runtime de agentes, publicados como paquetes @zetesis/. El servidor MCP vive aquí.
TypeScriptSeguir leyendo
Zetesis Portal y PayloadAgents: cómo construimos nuestro SaaS
Huygens: un grafo en SurrealDB como memoria para agentes
Consultoría de desarrollo agéntico
Un despliegue por cliente o un espacio por cliente
Búsqueda y agentes sobre tu propia documentación
