NotariumDocumentación
Versión de la documentación: latest
ES

Conectar un agente

En el corazón de Notarium, una misma base de conocimiento está igual de abierta a una persona y a un agente de IA. Tú trabajas a través del editor web y el agente lo hace a través del endpoint MCP integrado; sus ediciones se versionan, quedan acotadas por los permisos de acceso y llevan firma de procedencia exactamente igual que las tuyas. No hace falta levantar un servicio aparte para esto: la pasarela MCP vive en el mismo proceso y en el mismo puerto que la interfaz web.

Esta página es la vía rápida: emitir un token, apuntar al endpoint y comprobar que el agente ve tu base de conocimiento. El contrato completo (herramientas, convenciones de llamada, memoria, auditoría, seguridad) está en la sección Agentes y MCP.

Paso 1. Emitir un token

El agente se autentica con un token de acceso personal (PAT). Emite uno en los ajustes de tu cuenta (la sección de tokens): ahí mismo defines también:

  • el alcance — read o write (el techo de permisos del token);
  • el acotamiento por espacios opcional — qué espacios quedan accesibles;
  • una caducidad opcional.

El token tiene la forma ntp_<id>_<secret> y se muestra una sola vez: cópialo de inmediato. Un PAT filtrado no escala privilegios: las acciones de gestión (emitir tokens, membresía, crear espacios) solo están disponibles en una sesión humana, nunca mediante un token.

Los permisos del token son el techo del agente

Un token de solo lectura literalmente no ve las herramientas de escritura: nunca aparecen en su conjunto. El espacio de otro usuario es inalcanzable, y punto. Concede al agente exactamente los permisos que la tarea necesita.

Paso 2. Apuntar al endpoint

Configura el agente (o el cliente MCP) para que use el endpoint:

POST http://localhost:3000/mcp
Authorization: Bearer ntp_<id>_<secret>

El transporte es streamable-HTTP del SDK oficial de MCP, sin estado, una respuesta JSON por petición (GET/DELETE devuelven 405). El endpoint es compatible con el conector MCP de la Claude API y con cualquier cliente MCP por HTTP.

Los conectores web de claude.ai y chatgpt.com

No puedes pegar un PAT en los conectores personalizados de las interfaces web: solo funcionan por OAuth. Notarium incluye una fachada OAuth ligera: el conector se autentica con tu sesión y recibe un token que se asocia al mismo principal. Los detalles están en la sección Conectar un agente.

Paso 3. Primera llamada — start_session

En una sesión nueva, el agente llama a start_session primero. En una sola petición obtiene tu perfil, la lista de proyectos disponibles y el delta de cambios desde su última visita; y si le pasas una pista project, además un índice compacto de ese proyecto. Ese es el contexto desde el que empezar a trabajar.

A partir de ahí viene la rutina de siempre: examinar la estructura (list_notes, recent_activity), buscar antes de escribir (search — deduplicación) y luego escribir (create_note, edit_note, memoria mediante remember_about_user / remember_about_project). El agente trabaja a través de un conjunto reducido de herramientas acotadas a tareas concretas, y no mediante operaciones universales de lectura/escritura: cada herramienta impone un comportamiento seguro (la clase de la nota, la visibilidad, la procedencia, una comprobación de versión al guardar para no pisar las ediciones de otra persona).

No expongas una instancia none a la red

En el modo AUTH_MODE=none el endpoint /mcp está abierto sin token (un único principal con acceso total). Resulta cómodo para uso de escritorio y entornos de confianza, pero una instancia así nunca debe exponerse a una red pública.

Paso 4. Dejarlo escrito en las reglas del agente

Qué herramienta llamar lo decide el propio modelo, así que conviene anotar una sola vez el «llamar primero a start_session» en las instrucciones permanentes del agente (CLAUDE.md, AGENTS.md, las reglas de Cursor, el prompt de sistema), junto con el handle de tu proyecto:

- Al inicio de una sesión nueva, llama a `start_session(project: "acme/website")`
  en el servidor MCP `notarium`.
- Antes de escribir nada, haz siempre `search(...)`: no crees duplicados.

Sin eso, acabas señalándole la base de conocimiento al agente a mano una y otra vez. La versión larga —con un mapa de tu canon y el reparto entre reglas globales y reglas por proyecto— está en Reglas del agente.

Siguientes pasos