Conectar un agente

Un agente se comunica con Notarium a través de un único endpoint: POST /mcp. Es la pasarela MCP 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.

curl -sS https://notarium.example.com/mcp \
  -H "Authorization: Bearer ntp_<id>_<secret>" \
  -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 <pat>.

El formato del token es ntp_<id>_<secret>: 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).

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:

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).
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).
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.

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.

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).

Reglas del agente — cómo hacer que las sesiones arranquen con start_session sin que tengas que pedirlo cada vez.
Herramientas de intención — el conjunto completo de 21 herramientas y el orden de las llamadas.
Seguridad y visibilidad — cómo se aplican los permisos en cada llamada.
Inicio rápido: conectar un agente — un ejemplo mínimo de extremo a extremo.