Notarium文档
文档版本: latest
中

连接智能体

智能体通过单一端点 POST /mcp 与 Notarium 通信。这就是内置的 MCP 网关：与 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 客户端。

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 权限，也就是说令牌只能由你本人经会话签发，智能体自己永远签不出来（泄露的令牌签不出新令牌）。
令牌的权限即权限上限

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 板块里管理，改级别或改空间集合都不必再走一次授权确认。

Claude 与 ChatGPT 都走 OAuth

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

none 模式：不用令牌

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

authless 服务器等于对外公开

在 none 模式下，谁知道 URL，谁就能调用。这只在单用户、演示或受信网络的场景下可以接受。多用户实例请用 AUTH_MODE=password（默认值）。

下一步