NotariumDocumentation
Documentation version: latest
EN

Connect an agent

At the heart of Notarium, one and the same knowledge base is equally open to a human and to an AI agent. You work through the web editor, the agent works through the built-in MCP endpoint, and its edits are versioned, constrained by access rights, and signed with provenance exactly the way yours are. You don't need to stand up a separate service for this: the MCP gateway lives in the same process and on the same port as the web interface.

This page is the fast path: issue a token, point at the endpoint, and confirm the agent can see your knowledge base. The full contract (tools, calling conventions, memory, audit, security) lives in the Agents and MCP section.

Step 1. Issue a token

The agent authenticates with a personal access token (PAT). Issue one in your account settings (the tokens section) — that's also where you set:

  • scope — read or write (the token's permission ceiling);
  • optional space narrowing — which spaces are reachable;
  • an optional lifetime.

The token has the form ntp_<id>_<secret> and is shown exactly once — copy it right away. A leaked PAT doesn't escalate: management actions (issuing tokens, membership, creating spaces) are available only in a human session, never via a token.

A token's rights are the agent's ceiling

A read-only token literally can't see the writing tools: they never appear in its set. Another user's space is unreachable, period. Grant an agent exactly the rights the task needs.

Step 2. Point at the endpoint

Configure the agent (or MCP client) to use the endpoint:

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

The transport is streamable-HTTP from the official MCP SDK, stateless, one JSON response per request (GET/DELETE return 405). The endpoint is compatible with the Claude API MCP connector and any HTTP MCP client.

The claude.ai and chatgpt.com web connectors

You can't paste a PAT into the web interfaces' custom connectors — they work over OAuth only. Notarium ships a thin OAuth facade: the connector signs in with your session and receives a token that maps to the same principal. Details are in the Connecting an agent section.

Step 3. First call — start_session

In a new session the agent calls start_session first. In a single request it gets your profile, the list of available projects, and the delta of changes since its last visit — and if you pass a project hint, a compact index of that project too. That's the context to start your work from.

From there it's the familiar routine: survey the structure (list_notes, recent_activity), search before writing (search — dedup), then write (create_note, edit_note, memory via remember_about_user / remember_about_project). The agent works through a narrow set of tools scoped to specific tasks rather than through universal read/write operations — each tool enforces safe behavior (the note's class, visibility, provenance, a version check on save so it won't overwrite someone else's edits).

Don't expose a none instance to the network

In AUTH_MODE=none mode the /mcp endpoint is open without a token (a single all-access principal). That's handy for desktop use and trusted environments, but such an instance must never be exposed to a public network.

Step 4. Write it into the agent's rules

Which tool to call is the model's own decision, so "call start_session first" is worth writing down once, in the agent's standing instructions (CLAUDE.md, AGENTS.md, Cursor rules, the system prompt) — along with your project's handle:

- At the start of a new session, call `start_session(project: "acme/website")`
  on the `notarium` MCP server.
- Always `search(...)` before writing anything — don't create duplicates.

Without that, you end up pointing the agent at your knowledge base by hand every single time. The long version — with a map of your canon and the split between global and per-project rules — is in Agent rules.

Next