Conectando um agente

Um agente se comunica com o Notarium por um único endpoint — POST /mcp. É o gateway MCP integrado: o mesmo motor e os mesmos dados do editor web, mas com um conjunto restrito de ferramentas de intenção em vez de acesso direto ao armazenamento. Há duas formas de conectar um agente: um token de acesso pessoal (PAT), para clientes programáticos, ou um conector OAuth, para o claude.ai e o chatgpt.com no navegador.

Transporte: POST /mcp

O endpoint POST /mcp implementa o transporte streamable-HTTP do @modelcontextprotocol/sdk oficial. Ele é stateless: cada requisição sobe um servidor novo com as permissões do seu token e devolve uma única resposta JSON (não um fluxo SSE). GET e DELETE respondem 405 — aqui não existem fluxos iniciados pelo servidor.

O endpoint é compatível com o conector MCP da Claude API, com o Claude Code e com qualquer cliente HTTP-MCP capaz de enviar um 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"}'

Opção 1. Token de acesso pessoal (PAT)

O PAT é o caminho principal para clientes programáticos (Claude API, Claude Code, clientes MCP configuráveis). O token vai no cabeçalho Authorization: Bearer <pat>.

O formato do token é ntp_<id>_<secret>: o prefixo ntp_ deixa o token fácil de identificar em logs e vazamentos, a parte do id serve para a consulta rápida, e o segredo fica no banco apenas como hash e aparece uma única vez, no momento da emissão.

Há duas formas de emitir um token:

Pela interface — a seção de tokens nas configurações. Você define o nome, o nível (read ou write) e, se quiser, um escopo restrito a espaços específicos e um prazo de validade.
Pela API — POST /api/me/tokens. Exige a permissão self:manage, ou seja: só você emite um token, e sempre a partir de uma sessão — nunca o próprio agente (um token vazado não consegue emitir outro).

As permissões do token são um teto

Um token read sequer enxerga as ferramentas de escrita em tools/list — elas não "aparecem e recusam", simplesmente não estão na lista. O conjunto de espaços do token define até onde o agente alcança; o que estiver fora dele é inalcançável por design. As permissões podem ser alteradas depois da emissão (nome, nível, conjunto de espaços) sem recriar o segredo — a mudança vale a partir da chamada seguinte.

Opção 2. Conector OAuth para clientes web

As interfaces web do claude.ai e do chatgpt.com só aceitam OAuth na hora de adicionar um "custom connector" — não existe campo para colar um token Bearer. Por isso o Notarium traz uma fachada OAuth 2.1 enxuta (o Notarium atua como seu próprio Authorization Server — não há a quem delegar: numa auto-hospedagem, as contas são suas).

Como funciona:

Uma requisição a POST /mcp sem token retorna 401 com o cabeçalho WWW-Authenticate apontando para os documentos de discovery (RFC 9728 / RFC 8414).
O cliente passa por GET /oauth/authorize — você entra com a sessão atual e, na tela de consentimento, escolhe os espaços (seleção múltipla, com "All spaces" como padrão).
POST /oauth/token com PKCE (método S256) emite um access token (nto_…) e, com offline_access, um refresh token (ntr_…).

O token emitido é mapeado para o mesmo principal e validado no mesmo ponto de verificação que um PAT ou uma sessão. Seu nível é read ou write, mas nunca manage: um token de conector vazado não emite outro token nem concede acesso. As conexões você gerencia na seção Connected apps, onde também dá para mudar o nível ou o conjunto de espaços sem passar de novo pelo consentimento.

Claude e ChatGPT se conectam via OAuth

O Notarium entra no ChatGPT como um conector comum sobre o mesmo OAuth — igual ao claude.ai: login com a sessão atual, escolha dos espaços na tela de consentimento, e o agente vê seu conjunto habitual de ferramentas de intenção.

O modo none: sem token

Se uma instância for iniciada com AUTH_MODE=none (desktop, dev, uma intranet confiável — o operador desliga a autenticação de propósito), o gateway roda sem autenticação: /mcp age como um único principal com acesso total, e claude.ai/ChatGPT o adicionam como conector sem autenticação, sem configuração nenhuma. Nesse modo não existe fachada OAuth.

Um servidor sem autenticação é público

No modo none, quem souber a URL consegue chamá-lo. Isso só é aceitável em cenários de usuário único, demonstração ou rede confiável. Para uma instância multiusuário, use AUTH_MODE=password (o padrão).

A seguir

Regras do agente — como fazer a sessão já começar com start_session, sem você precisar pedir toda vez.
Ferramentas de intenção — o conjunto completo de 21 ferramentas e a ordem das chamadas.
Segurança e visibilidade — como as permissões são aplicadas em cada chamada.
Início rápido: conectar um agente — um exemplo mínimo de ponta a ponta.