---
title: "接入智能体"
description: "签发个人令牌，将智能体指向 POST /mcp 端点，并完成第一次 start_session 调用。"
---

# 接入智能体

Notarium 的核心在于：同一个知识库对人和 AI 智能体一视同仁地开放。你通过 Web 编辑器工作，智能体通过内置的 **MCP 端点**工作——它的每一次编辑都和你的完全一样：纳入版本历史、受访问权限约束、带上溯源签名。为此你无需另起一套服务：MCP 网关就跑在 Web 界面所在的同一个进程、同一个端口上。

本页是快速上手路径：签发令牌、指向端点、确认智能体能看到你的知识库。完整契约（工具、调用约定、记忆、审计、安全）见[智能体与 MCP](/docs/agents/)一节。

## 第 1 步：签发令牌

智能体使用**个人访问令牌（PAT）**进行认证。在账户设置的令牌区域签发一个——在同一处你还可以设置：

- **作用域（scope）**——`read` 或 `write`（令牌的权限上限）；
- 可选的**空间收窄**——哪些空间可达；
- 可选的**有效期**。

令牌形如 `ntp_<id>_<secret>`，且**只显示一次**——请立即复制。泄露的 PAT 不会带来权限升级：管理类操作（签发令牌、成员资格、创建空间）只在人类会话下可用，绝不通过令牌进行。

> [!warning] 令牌的权限即智能体的上限
> 只读令牌根本**看不到**写入类工具：它们从不出现在其工具集里。别人的空间彻底不可达。给智能体的权限，正好覆盖任务所需即可。

## 第 2 步：指向端点

将智能体（或 MCP 客户端）配置为使用该端点：

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

传输采用官方 MCP SDK 的 streamable-HTTP，无状态，每个请求返回一个 JSON 响应（`GET`/`DELETE` 返回 `405`）。该端点兼容 Claude API 的 MCP 连接器以及任何 HTTP MCP 客户端。

> [!note] claude.ai 与 chatgpt.com 的 Web 连接器
> 无法把 PAT 粘贴进这些 Web 界面的自定义连接器——它们只支持 OAuth。Notarium 自带一层轻量 OAuth 门面：连接器用你的会话完成登录，拿到一个映射到同一主体的令牌。详见[连接智能体](/docs/agents/connect/)一节。

## 第 3 步：首次调用——start_session

在新会话中，智能体**首先**调用 `start_session`。一次请求就能拿到你的个人资料、可用项目列表，以及自上次访问以来的变更增量——若再传入 `project` 提示，还会附带该项目的紧凑索引。这就是着手工作的上下文。

接下来是熟悉的流程：勘察结构（`list_notes`、`recent_activity`），**写前先搜**（`search`——去重），然后写入（`create_note`、`edit_note`，记忆则用 `remember_about_user` / `remember_about_project`）。智能体用的是一组针对具体任务收窄的工具，而不是通用的读写操作——每个工具都会强制安全行为（笔记的类别、可见性、溯源，以及保存时的版本校验，以免覆盖别人的编辑）。

> [!important] 不要把 `none` 实例暴露到网络
> 在 `AUTH_MODE=none` 模式下，`/mcp` 端点无需令牌即开放（单一的全权主体）。这对桌面使用和可信环境很方便，但这样的实例绝不能暴露到公网。

## 第 4 步：把它写进智能体规则

调用哪个工具是模型自己的决定，所以「先调用 `start_session`」这件事值得一次性写进智能体的常驻指令（`CLAUDE.md`、`AGENTS.md`、Cursor rules、系统提示词），并连同你的项目句柄一起写下：

```markdown
- 新会话开始时，在 `notarium` MCP 服务器上调用
  `start_session(project: "acme/website")`。
- 任何写入之前先 `search(...)`——不要制造重复。
```

不这么做，你就得每一次都手动把智能体指向你的知识库。更展开的版本——带规范地图，以及全局规则与项目级规则的划分——见[智能体规则](/docs/agents/agent-files/)。

## 下一步

- [智能体规则](/docs/agents/agent-files/)——让会话自己带着该有的上下文开场。
- [意图工具](/docs/agents/intent-tools/)——完整的工具集与调用约定。
- [智能体记忆](/docs/agents/memory/)——智能体如何记住你和项目。
- [安全与可见性](/docs/agents/security/)——工具集为何是现在这个样子。