---
title: "Connect an agent"
description: "Issue a personal token, point your agent at the POST /mcp endpoint, and make your first start_session call."
---

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

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

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

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

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

## Next

- [Agent rules](/docs/agents/agent-files/) — so a session starts with the right context on its own.
- [Intent tools](/docs/agents/intent-tools/) — the full tool set and calling conventions.
- [Agent memory](/docs/agents/memory/) — how the agent remembers you and the project.
- [Security and visibility](/docs/agents/security/) — why the tool set looks the way it does.