Odysseus AI MCP：サーバー、OAuth、トラブルシュートの設定方法

OdysseusのワークスペースでMCPが意味すること

Model Context Protocol（MCP）は、AIアプリケーションがサーバーの提供するツールを発見して呼び出すためのプロトコルです。ツールには、文書の読み取り、カレンダー検索、Web検索、タスク作成などがあります。サーバーは入力スキーマと実際の処理を定義し、ホストは接続の開始、表示するツール、ユーザーの承認を管理します。

Odysseus AI MCPを設定するとき、モデル、ワークスペース、MCPプロセスを一つの信頼ゾーンとして扱わないことが重要です。モデルが手元で動いていても、MCPサーバーはホストされたAPIへ検索語を送る場合があります。Odysseusの画面がローカルでも、リモートサーバーは別のネットワークにあります。秘密情報を渡す前に、その境界を書き出してください。

設定前に認証、管理者権限、ネットワークを確認する

公式のOdysseusセットアップ資料では、MCP管理とAPIトークン管理は管理者向けの領域です。権限を持つアカウントでログインし、Web画面を提供するプロセスが同じ環境変数を読み込んでいるか確認します。ブラウザでチャットが動くことは、サーバープロセスからMCPエンドポイントへ到達できる証拠にはなりません。

テスト中も認証を有効にしてください。管理画面を一時的に公開したり、モデルのポートを外部へ開けたりすると、元へ戻す作業が漏れやすくなります。Dockerで動かす場合は、OAuthのコールバックとサービス名がホストのブラウザだけでなくコンテナのネットワークから解決できる必要があります。DNS、TLS、ファイアウォール、許可されたオリジンも確認します。

内蔵MCPサーバーとnpxキャッシュを確認する

Odysseusには内蔵MCPサーバーの例があります。ただし、内蔵という表示だけでプロセスが正常とは限りません。コマンドが実行環境に存在し、想定した引数で起動し、サーバーが必要なランタイムへ到達できることを確認します。

例によってはnpxがローカルキャッシュのパッケージを起動します。初回はパッケージを解決し、次回からキャッシュを使うことがあります。許可されたパッケージとバージョンを記録してください。ネットワーク分離されたホストでは、承認済みのキャッシュを用意するか、ローカルにインストールしたコマンドを使います。

1. 低リスクの登録を選ぶ

   テスト用の文書一覧など、読み取りだけの例を選びます。シェルや広いファイル範囲は後回しにします。

2. 同じ実行環境を確認する

   Odysseusと同じイメージまたはコンテナでコマンドを実行し、stderrから秘密を取り除きます。

3. npxの解決を確認する

   キャッシュまたは許可されたレジストリへ到達できることと、解決したバージョンを確認します。

npx -y @playwright/mcp@latest --help

docker compose logs --tail=120 odysseus

OAuth付きリモートMCPサーバーを追加する

OAuthを使うリモートMCPサーバーでは、通常のトランスポートとツールのハンドシェイクに本人確認の交換が加わります。Odysseusのホストが認可を開始し、利用者がスコープを許可すると、提供者は登録済みのコールバックへブラウザを戻します。コンテナ内のlocalhostは、外部ブラウザの戻り先にはなりません。

Odysseusのセットアップ資料は、OAuth付きリモートMCPサーバーのためのOAUTH_REDIRECT_BASE_URLを説明しています。デプロイ環境で設定し、スキームとパスを安定させ、環境変数を読むプロセスを再起動してください。client secretをページ、プロンプト、スクリーンショット、コミット済みJSONへ貼り付けてはいけません。

1. コールバックを確認する

   サーバーの資料から正確なHTTPSパスとスコープを記録します。

2. OAUTH_REDIRECT_BASE_URLを設定する

   デプロイ環境へ追加して、読み込むサービスを再起動します。

3. Odysseusから認可する

   Odysseusでフローを開始し、想定したホストとパスへ戻ることを確認します。

OAUTH_REDIRECT_BASE_URL=https://mcp.example.com/oauth/callback

再現できるテスト手順を使う

Odysseus AI MCPのサーバーを追加または変更するたびに、同じ順番で確認します。ワークスペースの状態、サーバープロセス、プロトコルの一覧、既知の入力による1回の読み取りという順番です。推論、トランスポート、権限、提供者の障害を一つの接続エラーにまとめずに済みます。

サーバー名、ツール名、引数の形、ステータス、所要時間、安全なリクエストIDを記録します。トークン、認証ヘッダー、個人ファイルの中身、完全なプロンプトは記録から除きます。失敗時はスキーマとマスクしたサンプルだけを残してください。

1. Odysseusの状態を確認する

   MCP画面を開く前にWebプロセスと依存サービスを確認します。

2. サーバープロセスを確認する

   コマンド、トランスポート、環境、エンドポイントをログと照合します。

3. ツールとスキーマを一覧化する

   名前、必須引数、読み取りと書き込みの能力を確認します。

接続不能、権限、古い登録を正しい順番で直す

失敗した層から確認します。プロセスが起動しない場合はコマンド、パッケージ、作業ディレクトリ、環境を見直します。起動するのにツールが見えない場合はトランスポートとハンドシェイクを確認します。ツールは見えるが呼び出せない場合は引数、OAuthスコープ、クォータ、上流エンドポイントを確認します。モデルがツールを無視する場合はホスト側のtool callingも調べます。

トークンとネットワークの安全チェックを適用する

MCPは機能を組み合わせるため、目的を満たす最小構成が安全です。必要なフォルダ、ドメイン、操作だけを許可します。調査では読み取り専用を優先し、書き込みには画面上の承認を求め、OAuthとAPIキーのローテーションを決めます。ローカルのプロセスでも、外部の提供者へデータを送る可能性があります。

• 最初の接続にはテスト用アカウントまたはワークスペースを使う。
• コマンドとパッケージのバージョンを確認し、変更を追跡する。
• OAuthとAPIの認証情報を環境変数または秘密管理へ置く。
• フォルダ、ドメイン、ツールを必要最小限にする。
• ログではトークン、個人ファイル、完全なプロンプトをマスクする。