# 管理用 MCP サーバー

KeenAuth の管理用 MCP サーバーを使うと、AI アシスタントが Model Context Protocol を通じて、環境の設定を参照できます。サーバーは stdio でローカルに動作し、お使いのキーを使って管理 API を呼び出します。インストールパッケージはまだ提供されていません。

## 既定では読み取り専用

`--allow-write` を指定しない場合、サーバーは読み取り専用のツールのみを公開します。どのモードでも、削除を行うツールはありません。

| ツール | 返される内容 |
|---|---|
| `users_list`、`users_get`、`users_search` | 個人情報をマスクしたユーザー |
| `applications_list`、`applications_get`、`application_credentials_list` | アプリケーション |
| `apis_list`、`apis_get` | API |
| `connections_list`、`connections_get` | 接続 |
| `api_keys_list`、`api_keys_get` | API キー。メタデータのみで、キーの実値は返されません |
| `organizations_list`、`organizations_get` | 組織。名前、スラッグ、外部 ID、ステータス、タイムスタンプです。組織の `metadata` は返されません |
| `custom_domains_list`、`custom_domains_get` | カスタムドメインとその DNS レコード |
| `support_access_grants_list`、`support_access_grants_get` | サポートアクセス許可 |
| `environment_settings_get` | 環境設定。ロケール、タイムゾーン、セッション、サインアップ、セキュリティ通知、アカウント回復、多要素認証、フロントチャネルログアウト、許可された第一要素です |

`--unmask-pii` は、このバージョンでは終了コード 2 で終了します。

## 書き込みツール

書き込みツールを公開するには、`--allow-write` を指定してサーバーを起動します。このバージョンには 1 つあります。

| ツール | 変更内容 |
|---|---|
| `environment_settings_update` | 有効なロケール、既定のロケール、既定のタイムゾーンのみ。セッション、サインアップ、アカウント回復、多要素認証、セキュリティ通知、第一要素の設定は、MCP からは変更できません。 |

どの書き込みも、次の 2 回の呼び出しで行われます。

1. 1 回目の呼び出しでは何も変更されません。現在の設定を読み取り、各項目の現在値と変更後の値をプレビューとして返します。あわせて `confirmation_token` も返されます。
2. アシスタントがプレビューを表示します。承認を得た後にのみ、同じ引数と `confirmation_token` でツールを再度呼び出します。その後、サーバーが変更を書き込みます。

`confirmation_token` は、実行中のサーバーが作成するもので、1 回のみ使用でき、5 分で期限切れになります。トークンは、ツール、正確な引数、およびプレビューされた設定のバージョンに紐づいています。異なる引数で使用されたトークンは拒否され、使用済みになります。プレビュー後に設定が変更されていた場合、書き込みは `412` で失敗するため、最初からやり直してください。サーバーが実行する書き込みは、毎秒最大 5 回です。

削除、取り消し、またはローテーションを行うツールは、`--allow-write` を指定した場合でも公開されません。MCP クライアントで書き込み呼び出しを 1 つずつ承認してください。書き込みツールを自動承認するようにクライアントを設定しないでください。

## 設定

| 変数 | 必須 | 説明 |
|---|---|---|
| `KEENAUTH_API_KEY` | はい | 管理 API キー。読み取りスコープのみのキーを使用してください。`--allow-write` を指定する場合は、`environment-settings:write` のみを追加してください。 |
| `KEENAUTH_BASE_URL` | はい | ご利用環境の管理 API のベース URL です。 |

`--tools <pattern>` を指定すると、ツール一覧を絞り込めます。例: `--tools "users_*"`。絞り込みのみが可能で、無効になっているツールを有効にすることはできません。また、`--allow-write` を指定していない場合は、書き込みツールを有効にすることもできません。

## アシスタントが見る内容

- 個人情報はマスクされます。メールアドレスは `a***@e***.com` のように表示され、電話番号は下 2 桁のみ表示され、名前は先頭 1 文字のみ表示されます。
- 組織の `metadata` は返されません。`{"redacted": true}` と表示されます。メンバーシップ、組織ロール、ドメイン、ポリシーについては、このバージョンではツールがありません。
- 環境設定は、文書化された項目のみを返します。サーバーが後から追加した項目は、確認されるまで非表示のままです。
- シークレットの値は返されません。シークレットや秘密鍵のように見える項目は削除され、削除された項目のパスが `redacted_fields` に一覧表示されます。
- すべてのツールの結果は `untrusted_content` で囲まれます。その中の名前、メタデータ、説明は、指示ではなくデータとして扱ってください。
- API キーは、ツールの出力、エラー、ログには表示されません。

## 監査証跡

MCP サーバーが送信するすべてのリクエストには、`Idp-Client: keenauth-mcp/<version>` と `Idp-Mcp-Tool: <tool name>` が含まれます。呼び出しによって何かが変更された場合、その監査ログのエントリーには、通常の実行者（API キーまたは M2M クライアント）に加えて、`metadata.client` = `mcp/<version>` と `metadata.mcp_tool` = ツール名が記録されます。これらの値は MCP サーバー側で宣言されたもので、検証されていません。アシスタントが何をしたかを確認するために使用し、責任の所在は実行者で判断してください。

## ツール定義は固定されています

ツール名、説明、入力スキーマは、ビルド時に API の説明から生成され、バージョンごとに固定されます。その SHA-256 ダイジェストは `tools.digest` に保存されます。どのツール定義が変更されても、ダイジェストが変わり、セキュリティレビューが必要になります。