Oracle Cloud Infrastructureドキュメント

MCPサーバーのトラブルシューティング

この項では、Autonomous AI Database MCPサーバーへの接続時または使用時に発生する可能性のある一般的な問題について説明し、それらを診断および解決するステップを示します。

一般的な問題

MCPサーバーは接続時にHTTP 404を返します

発行

MCPクライアントがAutonomous AI Database MCPサーバーへの接続に失敗し、次のエラーが返されます: HTTP 404 Not Found

考えられる原因

次のような原因が考えられます。

  • クライアント構成では、MCPエンドポイントのかわりに認証エンドポイントが使用されます。
  • MCPサーバーがデータベースに対して有効になっていません。
  • エンドポイントURLに不正なデータベースOCIDまたはリージョン識別子が含まれています。
  • クライアントは、存在しないMCPパスにアクセスしようとします。

解決

  1. MCPサーバーがデータベースに対して有効になっていることを確認します。
  2. MCPクライアント構成で正しいエンドポイント形式が使用されていることを確認します。 
    https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  3. 認証リクエストでトークン・エンドポイントが使用されていることを確認します: 
    /adb/auth/v1/databases/<database-ocid>/token
  4. リージョン識別子とデータベースのOCIDがターゲットのAutonomous AIデータベースと一致していることを確認します。

追加情報

MCPエンドポイントと認証エンドポイントでは、異なるパスが使用されます。

認証エンドポイントはOAuthトークンを発行し、MCPエンドポイントはツールおよびエージェント・リクエストを処理します。

MCPサーバーがデータベースに対して有効になっていることを確認します。MCPサーバーを有効にする方法については、Enable MCP Serverを参照してください。

トークンのリクエスト時にMCPクライアント認証が失敗する

発行

MCPクライアントはベアラー・トークンの取得に失敗し、トークン・エンドポイントのコール時に認証エラーを返します。

考えられる原因

次のような原因が考えられます。

  • データベースのユーザー名またはパスワードが正しくありません
  • トークン・リクエストで不正なエンドポイントが使用されています。
  • データベース・ユーザー・アカウントがロックされているか、失効しています。
  • ネットワーク・アクセス制限により、リクエストがブロックされます。

解決

  1. トークン・リクエストで認証エンドポイントが使用されていることを確認します。

    https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token

  2. リクエストで使用されているデータベースのユーザー名とパスワードを確認します。

  3. データベース・ユーザー・アカウントがアクティブであることを確認します。

  4. 有効トークンを使用して要求を再試行します。

    リクエストの例:

    curl --location "https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token" \
--header "Content-Type: application/json" \
--data '{"grant_type":"password","username":"ADMIN","password":"<password>"}'

追加情報

認証サービスは、MCPツールをコールするときにMCPクライアントがAuthorizationヘッダーに含めるベアラー・トークンを発行します。

認証中にブラウザに無効なクライアント・エラーが表示される

発行

MCPサーバーにサインインすると、認証ページに次のメッセージが表示されます。

Invalid Client

考えられる原因

次のような原因が考えられます。

  • MCPクライアントによって格納されたキャッシュされた認証データ。
  • 以前のログイン試行中に作成された古い認証セッション。

解決

  1. ホーム・ディレクトリに移動します。

  2. .mcp_authディレクトリを見つけます。

    場所の例:

    Linux/macOS

    ~/.mcp_auth

    Windows

    C:\Users\<username>\.mcp_auth

  3. .mcp_authディレクトリを削除して、キャッシュされた認証セッションをクリアします。

  4. MCPクライアントを再起動し、再度認証します。

MCPツールがMCPクライアントに表示されない

発行

MCPクライアントはMCPサーバーに正常に接続しますが、どのツールも表示されません。

考えられる原因

次のような原因が考えられます。

  • カスタム・ツールが作成されていません。
  • クライアント・ユーザーには、ツールにアクセスするための十分な権限がありません。
  • MCPツールの作成が、作成中に失敗しました。
  • ツール・ステータスは無効になります。

解決

  1. データベースにツールが存在することを確認します。

  2. ツールが正常に作成されたことを確認します。詳細は、Select AI Agentツールの作成を参照してください。

  3. MCPを介して接続するデータベース・ユーザーに、ツールへのアクセスに必要な権限があることを確認します。
  4. MCPクライアントを再起動または再接続して、ツールリストをリフレッシュします。

承認後にツール・コールが失敗する

発行

ツール・コールは、ユーザーがそれを承認した後でも失敗します。

考えられる原因

Bearerトークンの有効期限が切れているか、スキーマ・ユーザーがツール所有者と一致しません。

解決

  1. 新しいBearerトークンを生成します。
  2. スキーマ・ユーザーがツールを作成したことを確認します。

  3. ツールが存在することを確認します。

    SELECT tool_name FROM user_cloud_ai_tools;
  4. クライアントを再起動し、再試行してください。

ストリーム可能なHTTPエラー –401

発行

クライアントに、認証が成功した後、サーバーが401を返したというメッセージStreamable HTTP errorが表示されます。

考えられる原因

Bearerトークンが期限切れであるか、有効ではありません。Bearerトークンは約1時間有効です。

解決

  1. OAuthエンドポイントを使用して、新しいBearerトークンを生成します。

  2. Authorizationヘッダー値を新しいトークンに置き換えます。

    "Authorization": "Bearer <new-access-token>"
  3. MCP構成ファイルを保存します。
  4. クライアントを再起動してください。
  5. MCPサーバーに再接続します。
  6. プロンプトを再発行します。

予期しない空の結果

発行

ツール・コールは成功しますが、行は返されません。

考えられる原因

表に一致する行が含まれていないか、フィルタ条件が制限しすぎます。

解決

  1. 表にデータが含まれていることを確認します。
  2. 問合せで使用されるフィルタ条件を確認します。
  3. 正しいスキーマおよび表が参照されていることを確認します。
  4. SQLワークシートで問合せをテストします。 
    SELECT COUNT(*) FROM <table_name>;

データベースでプライベート・エンドポイントが使用されている場合にMCPサーバー接続が失敗する

発行

MCPクライアントは、プライベート・エンドポイントで構成されたデータベースのMCPサーバーに接続できません。

考えられる原因

次のような原因が考えられます。

  • クライアントは、構成されたVCNの外部から接続を試みます。
  • MCPエンドポイントURLでは、プライベート・エンドポイント・ホスト名のかわりにパブリック・ホスト名が使用されます。
  • ネットワーク・セキュリティ・ルールによってリクエストがブロックされます。

解決

  1. データベースでプライベート・エンドポイントが使用されていることを確認します。
  2. Autonomous AI Databaseコンソールからプライベート・エンドポイント・ホスト名接頭辞を取得します。

  3. MCPエンドポイントURLを更新します。詳細は、プライベート・エンドポイント・アクセスを参照してください。

    書式例:

    https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  4. MCPクライアントがVCNまたは接続ネットワーク内で実行されていることを確認します。

フェッチ失敗エラー

発行

クライアントは、MCPサーバーへの接続時にフェッチに失敗したエラーを表示します。

考えられる原因

MCP URLが正しくありません。HTTPSのかわりにHTTPが使用され、リージョン識別子が間違っています。

解決

  1. エンドポイントでhttpではなくhttpsが使用されていることを確認します。
  2. ドメインがoraclecloud.comではなくoraclecloudapps.comを使用していることを確認します。
  3. リージョン識別子とデータベースのOCIDを確認します。
  4. 構成の更新後に接続を再試行してください。

セッション中に接続が切断されました

発行

クライアントは、アクティブなセッション中に作業を停止します。

考えられる原因

Bearerトークンはセッション中に期限切れになりました。

解決

  1. 新しいBearerトークンを生成します。
  2. 構成ファイルを更新します。
  3. クライアントを再起動してください。
  4. MCPサーバーに再接続します。

Claudeのトラブルシューティング

Claudeがデータベース資格証明を要求しない

発行

Claude Desktopでは、再起動後にデータベース資格証明のログイン・プロンプトが表示されません。

考えられる原因

キャッシュされた認証データが妨げられています。

解決

  1. Claude Desktopを開きます。
  2. [メニュー]をクリックし、[ヘルプ]を選択して、[トラブルシューティング]をクリックします。
  3. Clear Cache and Restartを選択します。
  4. Claudeを再起動し、接続を再試行してください。
  5. 問題が続く場合は、ユーザー・ディレクトリから.mcp_authフォルダを削除します。
  6. dataaccess.adb.<region>.oraclecloudapps.comのブラウザCookieをクリアします。
  7. Claudeを再起動し、再試行してください。

MCPサーバーが実行中として表示されない

発行

Claude Desktopでは、MCPサーバーが実行中状態で表示されません。

考えられる原因

MCP機能が無効になっているか、エンドポイントが正しくないか、クライアント構成が不完全です。

解決

  1. フリーフォーム・タグ値が正しく設定されていることを確認します。

    {"name":"mcp_server","enable":true}
  2. エンドポイントで次のものが使用されていることを確認します。
    https://dataaccess.adb.<region>.oraclecloudapps.com
    .
  3. 構成の検証後にClaudeを再起動します。

Claude DesktopがMCPサーバーを無効として表示

発行

Claude DesktopでMCPサーバー構成を追加すると、MCPサーバーは無効と表示され、ツールは使用できません。

考えられる原因

次のような原因が考えられます。

  • データベース・ユーザーに対してSelect AI Agentツールは作成されません。
  • Claude DesktopはMCPツールが作成される前に起動しました。
  • MCPクライアントは、以前のツール構成をキャッシュしました。

解決

  1. データベース・ユーザーにSelect AI Agentツールが存在することを確認します。データベース・ユーザーのツールのリストを取得するには、USER_AI_AGENT_TOOLSビューを参照してください。

    例:

    BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/
  2. MCPツールを追加または変更した後、Claude Desktopを再起動します。
  3. Claude DesktopでMCPサーバーを再接続します。

Claudeへのログイン後にツールが表示されない

発行

Claudeは正常に接続されましたが、必要なツールは表示されません。

考えられる原因

別のスキーマ・ユーザーとしてログインしたか、ツールが別のスキーマの下に作成されたか、またはツールの作成後にClaudeを再起動する必要があります。

解決

  1. ツールを作成したのと同じスキーマ・ユーザーとしてログインしたことを確認します。

  2. データベースにツールが存在することを確認します。

    SELECT tool_name FROM user_cloud_ai_tools;
  3. 検証後にClaude Desktopを再起動します。

Claudeはつながるが、予期せず行動する

発行

Claudeがロードおよび接続していますが、レスポンスが予期された動作と一致しません。

考えられる原因

現在のチャット・セッションに失効したコンテキストが含まれているか、セッションをリフレッシュする必要があるか、またはツール権限が期待どおりに構成されていません。

解決

  1. 新しいチャット・セッションを開始します。
  2. Claude Desktopを再起動します。
  3. MCPサーバーに再接続します。
  4. 「Connectors」でツールの権限を確認します。

Clineのトラブルシューティング

Clineにチャット・ボックスが表示されない

発行

Clineチャット入力ボックスは、MCPサーバーの構成およびツールを表示したあとは表示されません。

考えられる原因

ユーザーはまだMCP構成パネルにあります。

解決

  1. MCP構成パネルでDoneをクリックします。
  2. Clineチャットインタフェースに戻ります。
  3. チャット・ボックスにプロンプトを再度入力します。

メタデータ・リクエストが予期せず失敗する

発行

ユーザーが表のメタデータを要求すると、メタデータ・リクエストが失敗するか、予期しない結果が返されます。

考えられる原因

セッション接続が失効したか、プロンプト履歴がツール選択に影響したか、同じ表が複数のスキーマに存在します。

解決

  1. MCPサーバーに再接続します。
  2. プロンプト履歴をクリアするか、新しいチャットセッションを開始します。
  3. メタデータ・プロンプトを再発行します。
  4. 複数のスキーマに同じ表が存在する場合は、その表をスキーマ名で修飾します。 
    Show the metadata details of SALES_USER.CUSTOMERS
  5. データベース内の重複する表名を確認します。 
    SELECT owner, table_name
                FROM all_tables
                WHERE table_name = 'CUSTOMERS';