--- title: "Conectar un agente" description: "Emite un token personal, apunta tu agente al endpoint POST /mcp y realiza tu primera llamada a start_session." --- # 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](/docs/agents/). ## 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__` 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. > [!warning] 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__ ``` 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. > [!note] 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](/docs/agents/connect/). ## 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). > [!important] 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: ```markdown - 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](/docs/agents/agent-files/). ## Siguientes pasos - [Reglas del agente](/docs/agents/agent-files/) — para que la sesión arranque sola con el contexto adecuado. - [Herramientas de intención](/docs/agents/intent-tools/) — el conjunto completo de herramientas y las convenciones de llamada. - [Memoria del agente](/docs/agents/memory/) — cómo el agente te recuerda a ti y al proyecto. - [Seguridad y visibilidad](/docs/agents/security/) — por qué el conjunto de herramientas es como es.