---
title: "连接智能体"
description: "如何将 AI 智能体接入 Notarium：个人访问令牌（PAT）、面向 Web 客户端的 OAuth 连接器，以及 POST /mcp 传输。"
---

# 连接智能体

智能体通过单一端点 `POST /mcp` 与 Notarium 通信。这就是内置的 [MCP 网关](/docs/agents/intent-tools/)：与 Web 编辑器同一个引擎、同一份数据，只是把对存储的直接访问换成了一组收窄的意图工具。接入方式有两种：面向编程式客户端的个人访问令牌（PAT），以及面向浏览器里的 claude.ai 和 chatgpt.com 的 OAuth 连接器。

## 传输：POST /mcp

`POST /mcp` 端点实现的是官方 `@modelcontextprotocol/sdk` 的 streamable-HTTP 传输，而且是**无状态**的：每个请求都会新起一个服务器实例，带上你令牌的权限，返回单个 JSON 响应，而非 SSE 流。`GET` 和 `DELETE` 一律返回 `405`——这里没有由服务端发起的流。

该端点兼容 Claude API 的 MCP 连接器、Claude Code，以及任何能带上 Bearer 令牌的 HTTP-MCP 客户端。

```bash
curl -sS https://notarium.example.com/mcp \
  -H "Authorization: Bearer ntp_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## 方式一：个人访问令牌（PAT）

PAT 是编程式客户端（Claude API、Claude Code、可配置的 MCP 客户端）的首选路径。令牌放在 `Authorization: Bearer <pat>` 请求头里传递。

令牌格式为 `ntp_<id>_<secret>`：`ntp_` 前缀让它在日志和泄露数据里一眼可辨，id 部分供快速查找，secret 则只以哈希形式存进数据库，并且仅在签发那一刻显示一次。

签发令牌有两条路径：

- **在界面里**——设置中的令牌板块。填写名称、选定级别（`read` 或 `write`），还可以按需把作用域收窄到指定空间，并设置有效期。
- **通过 API**——`POST /api/me/tokens`。它要求 `self:manage` 权限，也就是说令牌只能由你本人经会话签发，智能体自己永远签不出来（泄露的令牌签不出新令牌）。

> [!important] 令牌的权限即权限上限
> `read` 令牌在 `tools/list` 里根本**看不到**写入类工具——它们不是「先冒出来、再拒绝」，而是压根不在列表中。令牌的空间集合决定了智能体能触及哪些空间；集合之外的一切，在设计上就不可达。签发之后，令牌的权限（名称、级别、空间集合）仍可修改，且无需重建 secret——改动自下一次调用起生效。

## 方式二：面向 Web 客户端的 OAuth 连接器

**claude.ai** 和 **chatgpt.com** 的 Web 界面在添加「custom connector」时只认 OAuth——那里根本没有粘贴 Bearer 令牌的输入框。为此 Notarium 自带一层轻量的 **OAuth 2.1 门面**，并由自己充当授权服务器（Authorization Server）——没有可委托的对象，账户本就归自托管实例所有。

工作方式：

1. 不带令牌请求 `POST /mcp`，会返回 `401`，并在 `WWW-Authenticate` 头里指向发现文档（discovery documents，RFC 9728 / RFC 8414）。
2. 客户端走一遍 `GET /oauth/authorize`——你用当前会话登录，在授权确认页勾选空间（可多选，默认为「All spaces」）。
3. `POST /oauth/token` 配合 PKCE（S256 方法）签发访问令牌（access token，`nto_…`）；请求了 `offline_access` 时，还会附带一个刷新令牌（refresh token，`ntr_…`）。

这样签发出的令牌映射到同一个主体，并在与 PAT、会话完全相同的检查点上校验。它的级别是 `read` 或 `write`，但**绝不会是 `manage`**：泄露的连接器令牌既签不出新令牌，也授不出访问权。连接本身在 Connected apps 板块里管理，改级别或改空间集合都不必再走一次授权确认。

> [!note] Claude 与 ChatGPT 都走 OAuth
> Notarium 添加进 ChatGPT，也只是同一套 OAuth 之上的一个普通连接器，跟 claude.ai 里一模一样：用当前会话登录，在授权确认页选好空间，智能体随即看到你惯常的那组意图工具。

## none 模式：不用令牌

如果实例以 `AUTH_MODE=none` 启动（桌面端、开发环境、受信内网——运维方是有意关掉认证的），网关便不做任何认证：`/mcp` 表现为单一的全权限主体，claude.ai / ChatGPT 开箱即可把它添加为免认证（authless）连接器。此模式下没有 OAuth 门面。

> [!warning] authless 服务器等于对外公开
> 在 `none` 模式下，谁知道 URL，谁就能调用。这只在单用户、演示或受信网络的场景下可以接受。多用户实例请用 `AUTH_MODE=password`（默认值）。

## 下一步

- [智能体规则](/docs/agents/agent-files/)——如何让会话固定以 `start_session` 开场，省得你每次手动提醒。
- [意图工具](/docs/agents/intent-tools/)——完整的 21 个工具与调用顺序。
- [安全与可见性](/docs/agents/security/)——权限如何在每一次调用上生效。
- [快速上手：接入智能体](/docs/getting-started/connect-agent/)——一个最小的端到端示例。