> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Didit MCP認証：Diditでログイン（OAuth）

> Didit MCPはPKCE付きOAuth 2.1で認証します。動的クライアント登録、リソースメタデータ、スコープ、役割、各クライアントからの接続方法を解説します。

Didit MCPは**Didit でログイン**(OAuth 2.1)で認証します。コンソールでの役割に付与された権限を持つDidit **ユーザー**として動作し、**APIキーによる認証方式はありません**。

***

## Didit でログイン

ホスト型サーバー(`https://mcp.didit.me/mcp`)はOAuth 2.1の**リソースサーバー**です。**Didit Business Console**(`business.didit.me`)は、同意画面をホストしトークンを発行する**認可サーバー**です。MCPクライアントは標準のフローを自動的に実行します。

**1. 検出**

クライアントはトークンなしで`/mcp`にPOSTし、`401`と`WWW-Authenticate: Bearer`ヘッダーを受け取ります。このヘッダーの`resource_metadata`は、保護されたリソースのメタデータ(RFC 9728)を指しています。

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

このドキュメントには、リソース(`https://mcp.didit.me/mcp`)、認可サーバー(`https://business.didit.me`)、およびサポートされるスコープが記載されています。オリジンのルートを先に確認するクライアント向けに、同じドキュメントが`https://mcp.didit.me/.well-known/oauth-protected-resource`でも提供されています。

**2. 登録 (動的クライアント登録)**

クライアントは`https://business.didit.me/.well-known/oauth-authorization-server`で認可サーバーのメタデータを読み取り、まだクライアントIDを持っていない場合は`registration_endpoint`で自身を登録します(RFC 7591)。お客様側で事前にプロビジョニングするものはありません。ループバックまたはネイティブのコールバックを使うローカルクライアント(Claude Code、Cursor、MCP Inspector)も、審査済みのコールバックを使うクラウドホスト型クライアント(Claude)も、この方法で登録されます。Diditが審査していないリモートのコールバックURLは`invalid_redirect_uri`で拒否されます。そのクライアントは、事前にオペレーターによる登録が必要です。

**3. 認可 (PKCE)**

クライアントはS256のPKCEチャレンジを付けて`https://business.didit.me/authorize`を開きます。サインイン(または登録)すると、要求されている権限が正確に表示されます。クライアントはパブリッククライアントです。トークンエンドポイントはクライアントシークレットを受け付けない(`token_endpoint_auth_methods_supported`は`none`)ため、認可コードをクライアントに結び付けるのはPKCEです。

**4. 同意**

承認すると、コンソールはそのアプリ用に、承認したスコープに紐付いたセッションを発行し、認可コードを返します。クライアントはこのコードを`token_endpoint`でアクセストークンとリフレッシュトークンに交換します。

**5. ツールの呼び出し**

クライアントはすべてのリクエストにアクセストークンを付けて送信します。MCPはDidit認証サービスに対してRFC 7662のトークンイントロスペクションでトークンを検証し(トークンはJWTではなく不透明なトークンです)、イントロスペクションのレスポンスから組織の権限を読み取り、そのリクエストの間は**あなた**として動作します。

### スコープ

リソースメタデータは3つのスコープを公開しています。同意画面には、クライアントが要求するスコープがわかりやすい言葉で表示されます。

| スコープ | 付与される内容 |
| - | - |
| `didit:management` | ワークスペースの管理: `organization`、`members`、`subscription`、`users`、`applications`、`workflows`、`customization`、`questionnaires`、`lists`、`webhooks`、`integrations`、`api-keys`、`audit-logs`、`roles`、`saml`、および`analytics`。 |
| `didit:verification` | 認証の実行とレビュー: `sessions`、`businesses`、`cases`、`networks`、`transactions`、`blocklist`、および`analytics`。 |
| `didit:staff` | Diditのスタッフアカウント専用です。通常のアカウントでは何も有効になりません。また、オープンソース版にはスタッフ専用のツールは定義されていません。 |

どちらのスコープにも`analytics`が含まれます。`lists`の管理には`didit:management`が必要で、`blocklist`へのアクセスには`didit:verification`が必要です。

[ツールリファレンス](https://docs.didit.me/ja/integration/mcp/tools.md)には、各ツールが属するスコープが記載されています。承認したスコープはトークンに含まれ、サーバー側で適用されます。そのため、`didit:verification`のみで接続したアプリは、あなた自身の役割では許可される場合でも、管理系の操作を拒否されます。認可サーバーはOpenIDスコープ(`openid profile email`)にも対応しています。これらのみを要求する接続では、あなたが誰であるかはわかりますが、それ以外の情報にはアクセスできません。

アプリの実際の権限は、承認したスコープとコンソールの役割の**共通部分**です。両者のうち広いほうになることはありません。

`didit_session_create`で認証セッションを作成するには、`didit:verification`スコープ**かつ**`create:sessions`または`write:sessions`を持つ役割が必要です。**開発者**の役割には`create:sessions`が含まれます。`didit:management`のみを承認した場合、役割に必要な権限があってもセッションは作成できません。

### 役割と権限

ホスト型のトークンは**あなた**を表すため、エージェントは1つの接続で**あなたが所属するすべての組織**にまたがって作業できます。アプリ横断型のツール(`didit_session_search`、`didit_analytics`、`didit_context_get`、およびその他の`*_search`ツール)は、それらすべての組織を自動的に集計します。

あなたの**役割は常に**Diditのバックエンドによって組織ごとに**適用されます**。各ツールは1つのバックエンド権限文字列に対応しています(例: `didit_session_update_status`には`write:sessions`、`didit_session_delete`には`delete:sessions`)。[ツールリファレンス](https://docs.didit.me/ja/integration/mcp/tools.md)にはツールごとの権限が記載されています。サーバーはリクエストを送信する前にも、イントロスペクションのレスポンスに含まれる組織の権限を使ってその権限を確認します。

* `enforce`モードでは、あなたの役割で実行できないツールは`tools/list`から除外され、それでも呼び出すと、権限名を示す`missing_scope`エラーが返されます(`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`)。
* `shadow`モード(サーバーのデフォルト)では、すべてのツールが一覧に表示され、呼び出しはバックエンドに送られます。役割に権限がない場合、バックエンドは`403`を返します。判定結果はサーバーの監査ログに記録されるだけです。

いずれの場合も、MCPがコンソールの役割で既に許可されている範囲を超える権限を付与することはありません。`READER`は一覧表示と読み取りができ、`OWNER`または`ADMIN`は書き込みと削除ができます。

### トークンの有効期間

承認されたアプリには、承認に使用したブラウザのセッションとは別の、専用のセッションが付与されます。アクセストークンの有効期間は短く、クライアントはリフレッシュトークンを使って自動的に更新します(`grant_types_supported`には`refresh_token`が含まれます)。更新後もアプリのスコープは維持され、そのアプリに紐付いたままです。更新に失敗した場合(例えばアプリの接続を解除した後など)、クライアントは次の呼び出し時に**Didit でログイン**を再度実行します。

コンソールからサインアウトしても、接続済みのアプリはサインアウトされません。また、アプリを切断しても、どこからもサインアウトされることはありません。

### アプリの切断

**1. コンソールから**

**Settings → Authentication → Connected apps**には、承認したすべてのアプリが、登録名と付与された権限とともに一覧表示されます。**切断**を押すと、そのアプリのアクセスは即座に終了します。アクセストークンとリフレッシュトークンの両方が無効になり、それ以外には影響しません。

**2. アプリから (RFC 7009)**

クライアントは、トークンを認可サーバーの`revocation_endpoint`にPOSTすることで、自身のアクセス権を返却できます。このエンドポイントは`https://business.didit.me/.well-known/oauth-authorization-server`のメタデータで公開されています。RFC 7009の要件どおり、呼び出しが成功するとトークンがまだ有効だったかどうかにかかわらず`200`が返るため、レスポンスからトークンが有効だったかどうかを知ることはできません。`503`は失効を適用できなかったことを意味します。トークンはまだ有効なものとして扱い、再試行してください。

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **APIキーを使わない理由**: すべてのMCPツールはユーザー単位のコンソールエンドポイント(`/organization/{org}/application/{app}/…`)を呼び出します。これらのエンドポイントは役割ごとの権限を持つBearerトークンで認可を行い、**`x-api-key`を拒否します**。アプリケーションのAPIキーは、自社のバックエンドから[REST API](https://docs.didit.me/openapi-25.json)を直接呼び出すため(セッションの作成など)のものであり、このMCP用ではありません。`didit_org_list_api_keys`はキーのメタデータを値を伏せた状態で表示します。生のキーを表示するツールは、ホスト型コネクターでは非表示になっています。

***

## 各クライアントからの接続

どのクライアントも同じフローを実行します。異なるのはURLの渡し方だけです。

> [tab] Claude
>
> Business Consoleの連携ページに表示されるディープリンクを使用します。このリンクを開くと、**Add custom connector**ダイアログに値が入力された状態でclaude.aiが開きます。
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> 内容を確認してから、**Log in with Didit**を完了してください。Claude Desktopでは、**Settings → Connectors → Add custom connector**で同じURLを使用します。詳しくは[Claudeを接続する](https://docs.didit.me/ja/integration/mcp/claude.md)をご覧ください。

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> 次に、Claude Code内で`/mcp`を実行してブラウザでのサインインを開始します。

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursorは初回使用時に自身を登録し、ブラウザを開きます。

> [tab] 汎用クライアント
>
> OAuth 2.1に対応した任意のStreamable HTTPクライアントで`https://mcp.didit.me/mcp`を指定します。クライアントは次の処理を行う必要があります。
>
> 1. `POST /mcp`を送信して`401`を受け取り、`WWW-Authenticate`から`resource_metadata`を読み取ります。
> 2. `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`を取得し、続いて`https://business.didit.me/.well-known/oauth-authorization-server`にある認可サーバーのメタデータを取得します。
> 3. クライアントIDを持っていない場合は、`registration_endpoint`で登録します。
> 4. `authorization_endpoint`でPKCE (S256)を用いた認可コードフローを実行し、`token_endpoint`でコードを交換します。
> 5. すべての`POST /mcp`で`Authorization: Bearer <access_token>`を送信します。
>
> OAuthに対応していないクライアントは、`npx -y mcp-remote@latest https://mcp.didit.me/mcp`を介して利用できます。これがクライアントに代わってステップ1〜5を実行します。

***

## 認証エラー

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

`/mcp`から`401`が返る場合は、トークンが存在しないか、期限切れか、失効しています。クライアントはトークンを更新するか、**Didit でログイン**をやり直す必要があります。

*特定の*ツールで`403`または`missing_scope`エラーが返る場合、通常は接続全体に問題があるのではありません。原因は、ご自身の**役割**にその権限がない(`READER`が書き込みを試みた場合など)か、そのツールに必要な**スコープなしで**接続が承認されたかのどちらかです。後者は、再接続して両方のスコープを承認すれば解決します。前者は役割の変更が必要です。

すべてのツールが失敗する場合は、コンソールの**Settings → Authentication → Connected apps**を確認してください。そこで切断されたアプリは、再度承認する必要があります。

***

> [card] [ツールリファレンス](https://docs.didit.me/ja/integration/mcp/tools.md)
>
> 各ツールの機能、スコープ、役割の権限。

> [card] [高度な設定](https://docs.didit.me/ja/integration/mcp/advanced.md)
>
> 役割、アプリ間の動作、セルフホスティング。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.