--- title: "Conectar un agente" description: "Cómo conectar un agente de IA a Notarium: un token de acceso personal (PAT), un conector OAuth para clientes web y el transporte POST /mcp." --- # Conectar un agente Un agente se comunica con Notarium a través de un único endpoint: `POST /mcp`. Es la [pasarela MCP](/docs/agents/intent-tools/) integrada: el mismo motor y los mismos datos que en el editor web, pero con un conjunto acotado de herramientas de intención en lugar de acceso directo al almacenamiento. Puedes conectar un agente de dos formas: con un token de acceso personal (PAT) para clientes programáticos, o con un conector OAuth para claude.ai y chatgpt.com en el navegador. ## Transporte: POST /mcp El endpoint `POST /mcp` implementa el transporte streamable-HTTP del `@modelcontextprotocol/sdk` oficial. Es **stateless**: cada petición levanta un servidor nuevo con los permisos de tu token y devuelve una sola respuesta JSON (no un stream SSE). Los métodos `GET` y `DELETE` responden `405`: aquí no hay streams iniciados por el servidor. El endpoint es compatible con el conector MCP de la Claude API, con Claude Code y con cualquier cliente HTTP-MCP capaz de enviar un token Bearer. ```bash curl -sS https://notarium.example.com/mcp \ -H "Authorization: Bearer ntp__" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Opción 1. Token de acceso personal (PAT) El PAT es la vía principal para clientes programáticos (Claude API, Claude Code, clientes MCP configurables). El token se pasa en la cabecera `Authorization: Bearer `. El formato del token es `ntp__`: el prefijo `ntp_` hace que el token sea fácil de detectar en logs y filtraciones, la parte del id sirve para la búsqueda rápida, y el secreto se guarda en la base de datos solo como hash y se muestra una única vez, en el momento de la emisión. Hay dos formas de emitir un token: - **En la interfaz** — la sección de tokens en los ajustes. Defines un nombre, un nivel (`read` o `write`) y, si quieres, un alcance acotado a espacios concretos y una caducidad. - **A través de la API** — `POST /api/me/tokens`. Requiere el permiso `self:manage`, lo que significa que solo tú puedes emitir un token —a través de una sesión— y nunca el propio agente (un token filtrado no puede emitir uno nuevo). > [!important] Los permisos de un token son un techo > Un token `read` ni siquiera **ve** las herramientas de escritura en `tools/list`: no es que «aparezcan y luego rechacen», simplemente no están en la lista. El conjunto de espacios de un token determina a qué espacios puede llegar el agente; todo lo que quede fuera es inalcanzable por diseño. Los permisos de un token se pueden cambiar tras la emisión (nombre, nivel, conjunto de espacios) sin recrear el secreto: el cambio surte efecto en la siguiente llamada. ## Opción 2. Conector OAuth para clientes web Las interfaces web de **claude.ai** y **chatgpt.com** solo aceptan OAuth cuando añades un «custom connector»: no hay ningún campo para pegar un token Bearer. Para esto, Notarium incorpora una **fachada OAuth 2.1** ligera (Notarium actúa como su propio Authorization Server: no hay a quién delegar; una instancia autoalojada es dueña de las cuentas). Cómo funciona: 1. Una petición a `POST /mcp` sin token devuelve `401` con una cabecera `WWW-Authenticate` que apunta a los documentos de discovery (RFC 9728 / RFC 8414). 2. El cliente pasa por `GET /oauth/authorize` — te autenticas con tu sesión actual y, en la pantalla de consentimiento, eliges espacios (selección múltiple, con «All spaces» por defecto). 3. `POST /oauth/token` con PKCE (el método S256) emite un access token (`nto_…`) y, con `offline_access`, un refresh token (`ntr_…`). El token emitido se asocia al mismo principal y se valida en el mismo punto de control que un PAT y una sesión. Su nivel es `read` o `write`, pero **nunca `manage`**: un token de conector filtrado no puede emitir un token nuevo ni conceder acceso. Puedes gestionar las conexiones y cambiar su nivel o su conjunto de espacios en la sección Connected apps sin volver a pasar por el consentimiento. > [!note] Claude y ChatGPT se conectan vía OAuth > Notarium se añade a ChatGPT como un conector cualquiera sobre el mismo OAuth, igual que en claude.ai: te autenticas con tu sesión actual, eliges espacios en la pantalla de consentimiento y el agente ve tu conjunto habitual de herramientas de intención. ## El modo none: sin token Si una instancia se lanza con `AUTH_MODE=none` (escritorio, dev, una intranet de confianza — el operador desactiva la autenticación de forma deliberada), la pasarela funciona sin autenticación: `/mcp` actúa como un único principal con acceso total, y claude.ai/ChatGPT lo añaden directamente como conector sin autenticación, sin configuración adicional. En este modo no hay fachada OAuth. > [!warning] Un servidor sin autenticación es público > En modo `none`, quien conozca la URL puede llamarlo. Eso solo es aceptable en configuraciones de un solo usuario, de demo o de red de confianza. Para una instancia multiusuario, usa `AUTH_MODE=password` (el valor por defecto). ## Siguiente - [Reglas del agente](/docs/agents/agent-files/) — cómo hacer que las sesiones arranquen con `start_session` sin que tengas que pedirlo cada vez. - [Herramientas de intención](/docs/agents/intent-tools/) — el conjunto completo de 21 herramientas y el orden de las llamadas. - [Seguridad y visibilidad](/docs/agents/security/) — cómo se aplican los permisos en cada llamada. - [Inicio rápido: conectar un agente](/docs/getting-started/connect-agent/) — un ejemplo mínimo de extremo a extremo.