Notariumドキュメント
ドキュメントのバージョン: latest
日

エージェントを接続する

Notarium の核心は、一つの同じナレッジベースが人間にもAIエージェントにも等しく開かれていることです。あなたはWebエディタで作業し、エージェントは組み込みの MCPエンドポイント を通じて作業します。そしてエージェントの編集も、あなたの編集とまったく同じようにバージョン管理され、アクセス権で制約され、来歴とともに署名されます。そのために別のサービスを立てる必要はありません。MCPゲートウェイは、Webインターフェースと同じプロセス・同じポートの中に同居しています。

このページは最短ルートです。トークンを発行し、エンドポイントを指定し、エージェントからナレッジベースが見えることを確かめます。完全な仕様(ツール、呼び出し規約、メモリ、監査、セキュリティ)は エージェントとMCP セクションにあります。

ステップ1. トークンを発行する

エージェントは 個人アクセストークン(PAT) で認証します。アカウント設定のトークンのセクションで発行してください。同じ場所で次の項目も指定します。

  • スコープ — read または write(そのトークンの権限上限)
  • スペースの絞り込み(任意) — どのスペースに到達できるか
  • 有効期限(任意)

トークンは ntp_<id>_<secret> という形をしていて、表示されるのは 一度きり です。その場でコピーしてください。PATが漏れても権限は昇格しません。管理系の操作(トークンの発行、メンバーシップ、スペースの作成)は人間のセッションからしか行えず、トークン経由では決してできないからです。

トークンの権限がエージェントの上限

read-only のトークンには、書き込み系のツールが文字どおり 見えません。そもそもツールセットに現れないのです。他人のスペースには一切到達できません。エージェントには、そのタスクに必要なぶんだけの権限を渡してください。

ステップ2. エンドポイントを指定する

エージェント(またはMCPクライアント)を、このエンドポイントに向けて設定します。

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

トランスポートは公式MCP SDKの streamable-HTTP で、ステートレス、1リクエストにつきJSONレスポンスが1つです(GET と DELETE は 405 を返します)。このエンドポイントは Claude API の MCP コネクタをはじめ、あらゆる HTTP-MCP クライアントと互換性があります。

claude.ai と chatgpt.com のWebコネクタ

Webインターフェースのカスタムコネクタに PAT を貼り付けることはできません。こちらはOAuth専用です。Notarium には薄いOAuthファサードが備わっていて、コネクタはあなたのセッションでサインインし、同じプリンシパルに対応づけられたトークンを受け取ります。詳しくは エージェントの接続 セクションへ。

ステップ3. 最初の呼び出し — start_session

新しいセッションで、エージェントが 最初に 呼ぶのは start_session です。この1回のリクエストで、あなたのプロフィール、利用できるプロジェクトの一覧、前回の訪問以降の変更差分が返ります。さらに project ヒントを渡せば、そのプロジェクトのコンパクトなインデックスも付いてきます。ここが作業を始めるためのコンテキストです。

あとはいつもの流れです。構造を眺め(list_notes、recent_activity)、書く前に検索し(search — 重複防止)、それから書き込みます(create_note、edit_note、メモリは remember_about_user / remember_about_project)。エージェントが使うのは、汎用的な読み書き操作ではなく、個別のタスクに絞り込まれた狭いツールセットです。それぞれのツールが安全な振る舞いを強制します(ノートのクラス、可視性、来歴、そして他人の編集を上書きしないための保存時のバージョンチェック)。

none のインスタンスをネットワークに出さない

AUTH_MODE=none モードでは /mcp エンドポイントがトークンなしで開いています(全アクセス権を持つ単一のプリンシパル)。デスクトップ利用や信頼できる環境では便利ですが、そうしたインスタンスを公開ネットワークに晒してはいけません。

ステップ4. エージェントのルールに書き込む

どのツールを呼ぶかを決めるのはモデル自身です。だからこそ「まず start_session を呼ぶ」は、エージェントの常設の指示(CLAUDE.md、AGENTS.md、Cursor rules、システムプロンプト)に一度だけ書き留めておく価値があります。あなたのプロジェクトのハンドルも添えて。

- 新しいセッションの冒頭で、`notarium` MCPサーバーの
  `start_session(project: "acme/website")` を呼ぶこと。
- 何かを書き込む前に、必ず `search(...)` すること — 重複を作らない。

これがないと、毎回手作業でエージェントにナレッジベースの在りかを指し示すはめになります。あなたの正典の地図と、グローバルなルールとプロジェクト単位のルールの分け方まで含めた詳しい版は エージェントのルール にあります。

次に