NotariumDocumentação
Versão da documentação: latest
PT

Conectar um agente

No coração do Notarium, uma mesma base de conhecimento fica igualmente aberta para uma pessoa e para um agente de IA. Você trabalha pelo editor web, o agente trabalha pelo endpoint MCP embutido, e as edições dele são versionadas, restritas por direitos de acesso e assinadas com proveniência exatamente como as suas. Não é preciso subir um serviço separado para isso: o gateway MCP vive no mesmo processo e na mesma porta que a interface web.

Esta página é o caminho rápido: emitir um token, apontar para o endpoint e confirmar que o agente enxerga sua base de conhecimento. O contrato completo (ferramentas, convenções de chamada, memória, auditoria, segurança) está na seção Agentes e MCP.

Passo 1. Emita um token

O agente se autentica com um token de acesso pessoal (PAT). Emita um nas configurações da sua conta (a seção de tokens) — é lá também que você define:

  • escopo — read ou write (o teto de permissões do token);
  • restrição por espaços opcional — quais espaços ficam acessíveis;
  • um tempo de vida opcional.

O token tem o formato ntp_<id>_<secret> e é exibido uma única vez — copie-o na hora. Um PAT vazado não escala privilégios: ações de gestão (emitir tokens, participação, criar espaços) só ficam disponíveis em uma sessão humana, nunca por token.

Os direitos de um token são o teto do agente

Um token somente leitura literalmente não enxerga as ferramentas de escrita: elas nunca aparecem no conjunto dele. O espaço de outro usuário é inacessível, ponto final. Conceda ao agente exatamente os direitos que a tarefa exige.

Passo 2. Aponte para o endpoint

Configure o agente (ou o cliente MCP) para usar o endpoint:

POST http://localhost:3000/mcp
Authorization: Bearer ntp_<id>_<secret>

O transporte é o streamable-HTTP do SDK oficial de MCP, stateless, uma resposta JSON por requisição (GET/DELETE retornam 405). O endpoint é compatível com o conector MCP da Claude API e com qualquer cliente MCP via HTTP.

Os conectores web do claude.ai e do chatgpt.com

Você não consegue colar um PAT nos conectores personalizados das interfaces web — eles funcionam apenas via OAuth. O Notarium traz uma fachada OAuth enxuta: o conector faz login com a sua sessão e recebe um token mapeado para o mesmo principal. Os detalhes estão na seção Conectando um agente.

Passo 3. Primeira chamada — start_session

Em uma sessão nova, o agente chama start_session primeiro. Em uma única requisição, ele recebe seu perfil, a lista de projetos disponíveis e o delta de mudanças desde a última visita — e, se você passar uma dica project, também um índice compacto desse projeto. Esse é o contexto para começar o trabalho.

A partir daí, é a rotina de sempre: examinar a estrutura (list_notes, recent_activity), buscar antes de gravar (search — deduplicação) e então escrever (create_note, edit_note, memória via remember_about_user / remember_about_project). O agente trabalha por meio de um conjunto restrito de ferramentas voltadas a tarefas específicas, e não por operações universais de leitura/escrita — cada ferramenta impõe um comportamento seguro (a classe da nota, a visibilidade, a proveniência, uma verificação de versão ao salvar para não sobrescrever as edições de outra pessoa).

Não exponha uma instância none à rede

No modo AUTH_MODE=none, o endpoint /mcp fica aberto sem token (um único principal com acesso total). Isso é prático para uso em desktop e ambientes confiáveis, mas uma instância assim nunca deve ser exposta a uma rede pública.

Passo 4. Registre isso nas regras do agente

Qual ferramenta chamar é decisão do próprio modelo, então vale registrar uma única vez a regra "chame start_session primeiro" nas instruções permanentes do agente (CLAUDE.md, AGENTS.md, regras do Cursor, o prompt de sistema) — junto com o handle do seu projeto:

- No início de uma nova sessão, chame `start_session(project: "acme/website")`
  no servidor MCP `notarium`.
- Antes de gravar qualquer coisa, sempre faça `search(...)` — não crie duplicatas.

Sem isso, sobra para você apontar o agente para a sua base de conhecimento na mão, toda vez. A versão longa — com um mapa do seu cânone e a divisão entre regras globais e de cada projeto — está em Regras do agente.

A seguir