---
title: "Conectar um agente"
description: "Emita um token pessoal, aponte seu agente para o endpoint POST /mcp e faça a primeira chamada start_session."
---

# 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](/docs/agents/).

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

> [!warning] 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.

> [!note] 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](/docs/agents/connect/).

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

> [!important] 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:

```markdown
- 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](/docs/agents/agent-files/).

## A seguir

- [Regras do agente](/docs/agents/agent-files/) — para que a sessão já comece com o contexto certo por conta própria.
- [Ferramentas de intenção](/docs/agents/intent-tools/) — o conjunto completo de ferramentas e as convenções de chamada.
- [Memória do agente](/docs/agents/memory/) — como o agente lembra de você e do projeto.
- [Segurança e visibilidade](/docs/agents/security/) — por que o conjunto de ferramentas tem essa cara.