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

エージェントの接続

エージェントは POST /mcp という単一のエンドポイントを通じてNotariumとやり取りします。これは組み込みのMCPゲートウェイです。Webエディタと同じエンジン、同じデータを扱いますが、ストレージに直接触れるのではなく、絞り込まれたインテントツールのセットだけを通します。接続方法は2通りあります。プログラムから使うクライアント向けの個人アクセストークン(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"}'

方法1. 個人アクセストークン(PAT)

PATは、プログラムから使うクライアント(Claude API、Claude Code、設定可能なMCPクライアント)向けの主要な経路です。トークンは Authorization: Bearer <pat> ヘッダーで渡します。

トークンの形式は ntp_<id>_<secret> です。ntp_ プレフィックスはログや流出したデータの中でトークンを見つけやすくするためのもの、id 部分は高速な検索のためのものです。そしてシークレットはデータベースにハッシュとしてのみ保存され、発行時にちょうど一度だけ表示されます。

トークンの発行方法は2通りあります。

  • UIから — 設定内のトークンのセクション。名前とレベル(read または write)を指定し、必要ならスコープを特定のスペースに絞り込み、有効期限も設定できます。
  • APIから — POST /api/me/tokens。self:manage 権限が必要です。つまりトークンを発行できるのはセッションを通じたあなた自身だけで、エージェント自身には決してできません(流出したトークンから新しいトークンを発行することはできません)。
トークンの権限は上限である

read トークンには、tools/list に書き込み系ツールがそもそも見えません。「出てきてから拒否される」のではなく、そもそもリストにないのです。トークンに紐づくスペースの集合が、エージェントの手の届く範囲を決めます。その外側は、設計上たどり着けません。トークンの権限(名前、レベル、スペースの集合)は発行後でもシークレットを作り直すことなく変更でき、次の呼び出しから有効になります。

方法2. Webクライアント向けのOAuthコネクタ

claude.ai と chatgpt.com のWebインターフェースは、「custom connector」の追加時にOAuthしか受け付けません。Bearerトークンを貼り付ける欄がそもそもないのです。そのためにNotariumは薄いOAuth 2.1ファサードを備えています(Notarium は認可サーバー(Authorization Server)を自前で兼ねます。委譲する相手はいません — セルフホストではアカウントを自分で持っているからです)。

仕組みは次のとおりです。

  1. トークンなしで POST /mcp にリクエストすると、ディスカバリドキュメント(RFC 9728 / RFC 8414)を指す WWW-Authenticate ヘッダー付きで 401 が返ります。
  2. クライアントは GET /oauth/authorize に進みます。ここで現在のセッションでログインし、同意画面でスペースを選びます(複数選択、デフォルトは「All spaces」)。
  3. PKCE(S256メソッド)付きの POST /oauth/token が、アクセストークン(nto_…)を発行し、offline_access があればリフレッシュトークン(ntr_…)も返します。

発行されたトークンは、PATやセッションと同じプリンシパルに対応づけられ、同じチェックポイントで検証されます。レベルは read または write で、manage になることは決してありません。流出したコネクタトークンでは、新しいトークンの発行も、アクセスの付与もできません。接続の管理と、そのレベルやスペースの集合の変更は、同意をやり直すことなく Connected apps のセクションから行えます。

ClaudeとChatGPTはOAuthで接続する

NotariumはChatGPTにも、同じOAuthの上に載る通常のコネクタとして追加できます。claude.ai と同じで、現在のセッションでログインし、同意画面でスペースを選べば、エージェントにはいつものインテントツールのセットが見えます。

none モード: トークンなし

インスタンスを AUTH_MODE=none で起動した場合(デスクトップ、開発環境、信頼できるイントラネット — オペレーターが意図的に認証を切る場面)、ゲートウェイは認証なしで動きます。/mcp はすべてにアクセスできる単一のプリンシパルとして振る舞い、claude.ai や ChatGPT には、Notarium をそのまま authless コネクタとして追加できます。このモードにOAuthファサードはありません。

authlessサーバーは誰にでも開いている

none モードでは、URLを知っている人は誰でも呼び出せます。これが許されるのは、シングルユーザー、デモ、信頼できるネットワークの構成に限られます。マルチユーザーのインスタンスでは AUTH_MODE=password(デフォルト)を使ってください。

次へ