---
title: "エージェントの接続"
description: "AIエージェントをNotariumに接続する方法 — 個人アクセストークン(PAT)、Webクライアント向けのOAuthコネクタ、そして POST /mcp トランスポート。"
---

# エージェントの接続

エージェントは `POST /mcp` という単一のエンドポイントを通じてNotariumとやり取りします。これは組み込みの[MCPゲートウェイ](/docs/agents/intent-tools/)です。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クライアントと互換性があります。

```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"}'
```

## 方法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` 権限が必要です。つまりトークンを発行できるのはセッションを通じたあなた自身だけで、エージェント自身には決してできません(流出したトークンから新しいトークンを発行することはできません)。

> [!important] トークンの権限は上限である
> `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 のセクションから行えます。

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

## none モード: トークンなし

インスタンスを `AUTH_MODE=none` で起動した場合(デスクトップ、開発環境、信頼できるイントラネット — オペレーターが意図的に認証を切る場面)、ゲートウェイは認証なしで動きます。`/mcp` はすべてにアクセスできる単一のプリンシパルとして振る舞い、claude.ai や ChatGPT には、Notarium をそのまま 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/) — 最小限のエンドツーエンドの例。