--- title: "Conectando um agente" description: "Como conectar um agente de IA ao Notarium: token de acesso pessoal (PAT), conector OAuth para clientes web e o transporte POST /mcp." --- # Conectando um agente Um agente se comunica com o Notarium por um único endpoint — `POST /mcp`. É o [gateway MCP](/docs/agents/intent-tools/) 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. ```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"}' ``` ## 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 `. O formato do token é `ntp__`: 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). > [!important] 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: 1. 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). 2. 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). 3. `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. > [!note] 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. > [!warning] 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](/docs/agents/agent-files/) — como fazer a sessão já começar com `start_session`, sem você precisar pedir toda vez. - [Ferramentas de intenção](/docs/agents/intent-tools/) — o conjunto completo de 21 ferramentas e a ordem das chamadas. - [Segurança e visibilidade](/docs/agents/security/) — como as permissões são aplicadas em cada chamada. - [Início rápido: conectar um agente](/docs/getting-started/connect-agent/) — um exemplo mínimo de ponta a ponta.