OIC Monitoring MCP Server

Oracle Integration Cloud（OIC）向けの読み取り専用MCPサーバーです。MCPクライアント（Claude Codeなど）を接続し、統合、接続、ランタイムインスタンス、エラー、フローログについて平易な言葉で質問すると、サーバーがそれらをOIC REST API呼び出しに変換し、クリーンでLLMに適したJSONを返します。

FastAPI + WebSocketで構築され、OAuth2 Client Credentials（IDCS/IAM）で認証します。

目次

• 要件

• インストール: Windows、macOS、Linux

• 構成

• MCPクライアントを接続する

• 1つのコードベースから複数の環境を実行する

• サーバーを起動し続ける

  • オプションA: セッション限定

  • オプションB: 常駐バックグラウンドサービス

• ツール

• レスポンス形式

• 仕組み

• 本番環境での堅牢化

• トラブルシューティング

要件

ディスク占有量は小さく、仮想環境はおよそ120MB、ログは合計約60MBに制限されています。

インストール

手順はすべてのプラットフォームで共通です：

1. Python 3.10以上をインストールする

2. コードを取得する

3. 仮想環境を作成し、依存関係をインストールする

4. .envを作成して値を入力する

5. サーバーを起動して確認する

OSによって異なるのは、ステップ1と仮想環境のアクティベーションコマンドのみです。

Windows

1. Pythonのインストール

最も簡単な方法は、PowerShellでwingetを使用することです：

winget install -e --id Python.Python.3.12

または、python.org/downloads/windowsからインストーラーをダウンロードします。インストーラーを使用する場合は、最初の画面で 「Add python.exe to PATH」 にチェックを入れます。この1つのチェックボックスが、後に発生する「python is not recognized」問題の大半の原因です。

PowerShellを閉じて開き直し、確認します：

py -3 --version

Python 3.10.x以降が表示されるはずです。pyランチャーは公式インストーラーに同梱されており、WindowsでPythonを起動する最も確実な方法なので、以下のコマンドではこれを使用します。

2. コードの取得

git clone <your-repo-url> oic-mcp
cd oic-mcp

3. 仮想環境の作成と依存関係のインストール

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

PowerShellが「running scripts is disabled」というエラーでアクティベーションスクリプトをブロックした場合は、ユーザー単位で署名済みローカルスクリプトを一度だけ許可します。

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

PowerShellではなくcmd.exeを使用していますか？ .venv\Scripts\activate.batでアクティベートします。

4. 設定

Copy-Item .env.example .env
notepad .env

設定に記載されている値を入力します。

5. サーバーを起動

.\scripts\run-local.ps1

macOS

1. Pythonのインストール

macOSにはシステムPythonが同梱されていますが、これを対象にビルドすることは避けてください。Homebrewで独自のPythonをインストールします。

brew install python@3.12

続いて、確認します。

python3 --version

Homebrewがない場合は、先にHomebrewをインストールするか、python.org/downloadsmacosからmacOS用インストーラーをダウンロードします。

2. コードを取得

git clone <your-repo-url> oic-mcp
cd oic-mcp

3. 仮想環境を作成し、依存関係をインストール

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

4. 設定

cp .env.example .env
nano .env

5. サーバーを起動

chmod +x scripts/*.sh
./scripts/run-local.sh

Linux

1. Pythonのインストール

Debian / Ubuntu：

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git

python3-venvパッケージはDebianoは別途用意されており、見落としがちです。これがないと、python3 -m venvは「ensurepip is not available」エラーで失敗します。

RHEL / Rocky / Alma / Fedora：

sudo dnf install -y python3.12 python3.12-devel git

バージョンを確認する：

python3 --version

ディストistributionが3.10未満の場合（たとえばRHEL 8、標準では3=3.6）は、システムのものに加えて新しいインタプリタ（AppStreamやdeadsnakesからpython3.11またはpython3.12）をインストールし、仮想環境作成時にその明示的なバイナリを使用します（例：python3.12 -m venv .venv）。

2. コードを取得

git clone <your-repo-url> oic-mcp
cd oic-mcp

3. 仮想環境の作成し、依存関係をインストール

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

4. 設定

cp .env.example .env
nano .env

5. サーバーを起動

chmod +x scripts/*.sh
./scripts/run-local.sh

インストールの確認

サーバーは、デフォルトでws://127.0.0.1:8085/wsで待ち受けます。別のターミナルで：

python3 scripts/ws-call.py tools/list

Windowsの場合：

.\.venv\Scripts\python.exe scripts\ws-call.py tools/list

約40のツールのJSONリストが返されるはずです。WebSocketクライアントを必要としない、プレーンなHTTPヘルスチェックもあります。

curl http://127.0.0.1:8085/healthz
# {"status": "ok"}

接続エラーまたは401が発生した場合は、トラブルシューティングを参照してください。

ホストとポートの変更

run-local.shとrun-local.ps1はどちらもPORT変数を読み取り、指示がない限りループバックのみにバインドします。

# Linux / macOS
PORT=8086 ./scripts/run-local.sh
HOST=0.0.0.0 PORT=8086 ./scripts/run-local.sh

# Windows
$env:PORT="8086"; .\scripts\run-local.ps1
$env:MCP_HOST="0.0.0.0"; $env:PORT="8086"; .\scripts\run-local.ps1

または、uvicornを直接呼び出します。これは、スクリプトが内部で行っていることです。

uvicorn mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets

0.0.0.0にバインドすると、認証されていないWebSocketがネットワークに公開されます。TLSとファイアウォールの背後でのみ行ってください。本番運用を参照してください。

設定（.env）

.env.exampleを.envにコピーして、値を入力します：

機密アプリのクライアントには、OICインスタンスのリソースアプリに対してIDCS/IAMで**ServiceUser**アプリケーションロールが割り当てられている必要があります（クライアントアプリ自体ではなく）。そうでないと、有効なトークンがあってもすべての呼び出しが401エラーになります。トラブルシューティングを参照してください。

.envとすべての.env.*ファイルはgitignorになる（追跡されるのは.env.exampleのみ）ため、シークレットはリについてリポジトリに残りません。

MCPクライアントを接続する

Claude Code:

claude mcp add-json oic '{"type":"ws","url":"ws://127.0.0.1:8085/ws"}'

生のJSON設定をサポートするその他のクライアント：MCPサーバー設定にこれを追加します（例：.mcp.json、またはmcp.json.exampleをコピー）。

{
  "mcpServers": {
    "oic": {
      "type": "ws",
      "url": "ws://127.0.0.1:8085/ws"
    }
  }
}

このサーバーはWebSocketトランスポートのみをサポートしています。stdioサーバーではないため、"type": "stdio"やspawned-command設定はここでは機能しません。まずサーバを独自のプロセスとして起動し、クライアントをそのURLに向けてください。

接続後は、エージェントに「アクティブな統合を一覧表示」や「INTEGRATION_CODEの最新20件のランタイムインスタンスを表示」のように質問するだけで、自分でツール名を指定して呼び出す必要はありません。

1つのコードベースから複数の環境を実行する

Dev、Test、Prodを監視するために2つ目のクローンは必要ありません。1つのチェッされるアウトで必要な数だけプロセスを実行でき、各プロセスはOIC_ENV_FILEで独自のenvファイルを指し、各プロセスは独自のポートで実行されます。

mcp_server/settings.pyはプロセスの開始時にOIC_ENV_FILEを読み取り、そのファイルを.envの代わりに読み込みします。プロセスのその他はすべて同一（同じコード、同じツール）です。

1. 環境ごとに1つのenvファイルを作成

cp .env.example .env.dev
cp .env.example .env.test
cp .env.example .env.prod

各ファイルは、その環境のOIC_BASE_URL、OIC_INSTANCE_NAME、OAuth資格情報を入力し、ログが混ざらないようにそれぞれ個別のログファイルを指定します：

# in .env.prod
MCP_LOG_FILE=mcp_server.prod.log

2. 環境ごとに1つのプロセスを、それぞれ独自のポートで起動

Linux / macOS:

OIC_ENV_FILE=.env.dev  PORT=8085 ./scripts/run-local.sh
OIC_ENV_FILE=.env.test PORT=8086 ./scripts/run-local.sh
OIC_ENV_FILE=.env.prod PORT=8087 ./scripts/run-local.sh

Windows PowerShellは、各プロセスが独自の変数を設定するため、1つのターミナルにつき1つです。

$env:OIC_ENV_FILE=".env.prod"; $env:PORT="8087"; .\scripts\run-local.ps1

またはuvicornを直接呼び出します：

OIC_ENV_FILE=.env.prod uvicorn mcp_server.main:app --host 127.0.0.1 --port 8087 --ws websockets

3. 各プロセスをクライアントに、一意の別名で登録

{
  "mcpServers": {
    "oic-dev":  { "type": "ws", "url": "ws://127.0.0.1:8085/ws" },
    "oic-test": { "type": "ws", "url": "ws://127.0.0.1:8086/ws" },
    "oic-prod": { "type": "ws", "url": "ws://127.0.0.1:8087/ws" }
  }
}

エージェントは、明確に名前付けされた3つのツールセットを認識します。したがって、1つの会話内で複数の環境の同じ統合を比較要求できます。

推奨レイアウト:

知っておくとよいこと

• OIC_ENV_FILE詳しくは、プロセス起動時に一度読み取られます。環境変数を変更するか、envファイル自体を編集するには、そのプロセスの再起動が必要です。。

• 実際のOS環境変数は、envファイルのどんな内容よりも優先されます。OIC_BASE_URLシェルプロファイルに環境変数をエクスポートしている場合、どのenvファイルを読み込んだかに関係なく、すべてのプロセスがそれを使用します。これらの変数はシェルプロファイルに置かないでください。

• 各プロセスには独自のポートが必要です。同じポートの2つのプロセスは「アドレスはすでに使用中」エラーで発生します。

• Dockerでは、--env-fileは実際の環境変数を注入するため、そこではOIC_ENV_FILEは不要です。--env-fileを適切なファイルに指定するだけです。

• ここのすべてのツールは読み取り専用ですが、最小権限の原則は無料で適用できます。各環境のOAuthアプリにはServiceUserロールのみを付与します。

サーバーを起動し続ける

2つのサポートされるパターンがあります。意図的に1つ選択してください。ログアウト時の動作が大きく異なるためです。

オプションA: セッションのみ（ターミナルを閉じると終了する）

開発、アドホック調査、および一晩中はメモリに資格情報を保持しながらプロセスを放置したくない作業に最適です。

フォアグラウンドで、専用のターミナルウィンドウで実行：

# Linux / macOS
./scripts/run-local.sh

# Windows
.\scripts\run-local.ps1

それが全体の方法です。プロセスはそのターミナルの子プロセスです：

• Ctrl+Cで即停止します。

• ターミナルウィンドウを閉じる、SSHセッションを終了する、ログアウトすると、終了します。

• 自動再起動はなく、再起動後に復帰することはありません。

ログはターミナルとmcp_server.logに同時に出力されるため、このモードはデバッグの最も簡単な方法でもあります。

プロンプトに戻りたいが、プロセスをセッションで終了したい場合は、デーモン化ではなくシェルジョブ、のバックグラウンドとして実行します。

./scripts/run-local.sh > uvicorn.log 2>&1 &
echo "started as PID $!"

# later, from the same shell
kill %1

セッション内だけで動作させたいのであれば、nohup、setsid、disown、screen、tmux でラップしないでください。これらはすべてプロセスをセッションから切り離すためのもので、ログアウト後もプロセスを生存させ続けます。

セッションを閉じた後に何も残っていないことを確認するには:

# Linux / macOS
pgrep -af "mcp_server.main"

# Windows
Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
  Where-Object { $_.CommandLine -like "*mcp_server.main*" } |
  Select-Object ProcessId, CommandLine

オプションB: 永続的なバックグラウンドサービス（再起動後も生存）

共有サーバーや、チームがMCPエンドポイントを常時利用できることを前提とするワークステーションに最適です。以下のどのケースでも、サービスは起動時に開始され、クラッシュした場合は自動的に再起動します。

この用途には nohup ... & を使わないでください。ログアウトしてもプロセスは残りますが、再起動には耐えられず、プロセスが死んでも再起動されません。OSのサービス管理機能を使ってください。

Linux（systemd）

/etc/systemd/system/oic-mcp.service を作成します:

[Unit]
Description=OIC Monitoring MCP Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=oicmcp
Group=oicmcp
WorkingDirectory=/opt/oic-mcp
Environment=OIC_ENV_FILE=/opt/oic-mcp/.env.prod
ExecStart=/opt/oic-mcp/.venv/bin/uvicorn mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets
Restart=always
RestartSec=5

# Basic hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target

次に:

sudo useradd --system --home /opt/oic-mcp --shell /usr/sbin/nologin oicmcp
sudo chown -R oicmcp:oicmcp /opt/oic-mcp
sudo chmod 600 /opt/oic-mcp/.env.prod

sudo systemctl daemon-reload
sudo systemctl enable --now oic-mcp
sudo systemctl status oic-mcp

enable は再起動後にサービスを復活させ、Restart=always はクラッシュ後にプロセスを再起動します。この2つは両方必要です。

ログはジャーナルに出力されます:

journalctl -u oic-mcp -f

2番目の環境 を用意するには、ユニットを oic-mcp-test.service にコピーし、Environment=OIC_ENV_FILE= の行と --port を変更してから、sudo systemctl enable --now oic-mcp-test を実行します。

自分のユーザーとして実行したい場合は、同じユニットを ~/.config/systemd/user/oic-mcp.service に置き、systemctl --user enable --now oic-mcp で有効化し、sudo loginctl enable-linger $USER を実行します。これにより、最初のログイン時ではなく起動時に開始されるようになります。

macOS（launchd）

~/Library/LaunchAgents/com.oic.mcp.plist を作成し、/Users/you/oic-mcp を実際のパスに置き換えます:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.oic.mcp</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/oic-mcp/.venv/bin/uvicorn</string>
    <string>mcp_server.main:app</string>
    <string>--host</string><string>127.0.0.1</string>
    <string>--port</string><string>8085</string>
    <string>--ws</string><string>websockets</string>
  </array>

  <key>WorkingDirectory</key>
  <string>/Users/you/oic-mcp</string>

  <key>EnvironmentVariables</key>
  <dict>
    <key>OIC_ENV_FILE</key>
    <string>/Users/you/oic-mcp/.env.prod</string>
  </dict>

  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>

  <key>StandardOutPath</key>
  <string>/Users/you/oic-mcp/launchd.out.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/oic-mcp/launchd.err.log</string>
</dict>
</plist>

読み込みます:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.oic.mcp.plist
launchctl print gui/$(id -u)/com.oic.mcp | head -20

RunAtLoad は起動時にすぐ、そしてログインのたびに開始します。KeepAlive はプロセスが終了したときに再起動します。

停止するには、または plist 編集後に再読み込みするには:

launchctl bootout gui/$(id -u)/com.oic.mcp
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.oic.mcp.plist

~/Library/LaunchAgents 内の LaunchAgent は、あなたがログインしたときに起動します。誰もログインする前にマシンがエンドポイントを提供しなければならない場合は、同じ plist を /Library/LaunchDaemons/ に置き（所有者 root:wheel、モード 644）、root として実行されないように UserName キーを追加し、sudo launchctl bootstrap system /Library/LaunchDaemons/com.oic.mcp.plist で読み込んでください。

2番目の環境を用意する場合は、新しい Label（com.oic.mcp.test）と異なるポート、異なる OIC_ENV_FILE を指定して plist を複製します。

Windows（NSSM、推奨）

NSSM は、任意の実行可能ファイルを本格的な Windows サービスとしてラップします。winget install nssm または choco install nssm でインストールし、次に 管理者 PowerShell で:

$proj = "D:\oic_mcp_git"

nssm install OicMcp "$proj\.venv\Scripts\uvicorn.exe" "mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets"
nssm set OicMcp AppDirectory $proj
nssm set OicMcp AppEnvironmentExtra "OIC_ENV_FILE=$proj\.env.prod"
nssm set OicMcp Start SERVICE_AUTO_START
nssm set OicMcp AppStdout "$proj\service.out.log"
nssm set OicMcp AppStderr "$proj\service.err.log"
nssm set OicMcp AppExit Default Restart
nssm set OicMcp AppRestartDelay 5000

nssm start OicMcp

SERVICE_AUTO_START が再起動後にサービスを復元し、AppExit Default Restart がクラッシュ後に再起動します。

他のサービスと同じように管理します:

Get-Service OicMcp
nssm restart OicMcp
nssm stop OicMcp
nssm remove OicMcp confirm

2つ目の環境で利用するには、別の名前（OicMcpTest）で独自のポートと OIC_ENV_FILE を持つ別のサービスをインストールします。

Windows（タスクスケジューラ、追加ツール不要）

NSSM をインストールできない場合、タスクスケジューラで起動時に起動できます。まず、プロジェクトフォルダーに start-prod.bat を作成します。スケジュールタスクはインラインで作業ディレクトリを設定しにくいためです:

@echo off
cd /d D:\oic_mcp_git
set OIC_ENV_FILE=D:\oic_mcp_git\.env.prod
".venv\Scripts\python.exe" -m uvicorn mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets

次に、管理者 PowerShell で登録します:

schtasks /Create /TN "OIC MCP Server" /TR "D:\oic_mcp_git\start-prod.bat" /SC ONSTART /RU SYSTEM /RL HIGHEST /F
schtasks /Run /TN "OIC MCP Server"
schtasks /Query /TN "OIC MCP Server"

これは起動時には開始しますが、デフォルトではクラッシュ時に再起動しません。タスクスケジューラのタスクの 設定 タブで「タスクが失敗した場合、1分ごとに再起動する」を追加し、最大3回までに設定します。この点は NSSM の方が優れているため、NSSMが推奨されます。

Docker（任意のプラットフォーム）

再起動ポリシーは、Docker デーモン自体が起動時に開始する限り、ホストの再起動をまたいでもサービス管理者と同じ役割を果たします:

docker build -t oic-mcp:latest .

docker run -d \
  --name oic-mcp-prod \
  --restart unless-stopped \
  -p 8085:8080 \
  --env-file .env.prod \
  oic-mcp:latest

コンテナは内部で 8080 番ポートを待ち受けるため、任意のホストポートをマッピングしてください。2つ目の環境は、名前、ホストポート、env ファイルを変更して実行します:

docker run -d --name oic-mcp-test --restart unless-stopped \
  -p 8086:8080 --env-file .env.test oic-mcp:latest

docker ps と docker logs -f oic-mcp-prod で確認します。

どちらを使うべきか？

ツール

すべてのツールは tools/list で確認でき、読み取り専用です。多くはオプションの version を受け付けます。省略時は自動的に最新バージョンが解決されます。

インテグレーション

• list_integrations - オプション: onlyActivated、limit、page

• list_activated_integrations

• get_integration - identifier と version で指定

• get_integration_auto - code または code|version によるデザイン時の詳細、最新を自動解決

• search_integration_by_name - 全カタログ検索（自動ページング）。完全一致または部分一致。常にリストを返す

• list_integrations_search - code/name/description/keywords に対するクライアント側ページング検索

• export_integration - インテグレーションZIPをbase64でダウンロード、またはエントリとプレビューの listOnly

実行時監視

• list_instances - オプション: integrationId、status、startTime/endTime、timewindow、limit

• get_instance - instanceId による完全な詳細

• get_instance_activity_stream - 単一インスタンスのステップ単位のフロー/実行ログ

• list_errors - オプション: integrationId、timewindow、limit

• list_metrics - 過去のトラッキングメトリクス。時間単位または日単位

• list_schedules / get_schedule - インテグレーションごとのスケジュール情報

接続、パッケージ、構成部品

• list_connections / get_connection / get_connection_detail

• list_packages / get_package

• list_lookups / get_lookup

• get_library

• list_adapters / get_adapter

• list_agents / list_agent_groups

• list_endpoints - ロールと接続先を含むインテグレーションエンドポイント

デザイン時分析

• summarize_integration - トリガー/ターゲット/トラッキング変数を一覧表示

• summarize_integration_with_steps - 上記に加えて、選択したステップのI/O概要

• summarize_flow_controls - Switch/ForEach/Route/Fault/Scope 構文の数とサンプルをまとめる

• summarize_mappings - マッピングステップを抽出

• deep_flow_outline - フロー全体をコンパクトなテキストアウトラインで表示

• get_integration_step - stepName（完全一致 + あいまい一致）に一致する生のJSONサブツリーと、一致するエンドポイント

• summarize_step_io - stepName に対する疑わしいSQL/クエリスニペットとパラメータ。ステップが見つからない場合はエンドポイント一致にフォールバック

ユーティリティ

• fetch_raw_path - 任意の相対OICパスを取得

• search_json - 任意のJSON形式の構造に対する部分文字列検索

デザイン時ツールは、オプションの designJsonPath を受け入れて、OIC を呼び出す代わりに以前にダウンロードしたデザインJSONをディスクから読み取ることができます。オフライン分析や、反復作業中の重複呼び出し回避に役立ちます。

レスポンス形式

すべての tools/call 結果は MCP 仕様のエンベロープに従います: {"content": [{"type": "text", "text": "<json-or-plain-text>"}], "isError": false}。実際のツールペイロードは text 内に JSON シリアライズされています。構造化データを得るにはもう一度パースします:

python3 scripts/ws-call.py tools/call '{"name":"list_integrations","arguments":{"limit":3}}' \
  | python3 -c "
import json, sys
resp = json.load(sys.stdin)
payload = json.loads(resp['result']['content'][0]['text'])
print(json.dumps(payload, indent=2))
"

ツール実行エラー（OIC に到達できない、不正な識別子など）も同じ形式で isError: true とともに返ってきます。成功を前提とせず、そのフラグを確認してください。真正のプロトコルエラー（未知のメソッド、未知のツール名）は、実際の JSON-RPC error オブジェクトとして返されます。大きなペイロードは 100,000 文字に制限され、切り詰められた場合には、黙ってではなく明確に [TRUNCATED ...] とマークされます。

動作の仕組み

• サーバーは JSON-RPC 2.0 / MCP を話す WebSocket エンドポイントを1つ公開します。クライアントは tools/list でツールを発見し、tools/call で実行します。

• 呼び出しのたびに、認証済みの httpx.AsyncClient を介して OIC の REST API から取得します。OAuth トークンはキャッシュされ、期限が切れると自動的に更新されます。

• WebSocket ハンドシェイクでは、クライアントが提供する場合 mcp サブプロトコルをネゴシエートします。initialize は、仕様準拠の protocolVersion とオブジェクト型の capabilities を返します。これは Claude Code のような厳格なクライアントが接続を受け入れるために必要です。

• リダイレクトは httpx の組み込み処理ではなく手動でフォローされます。OIC のデザイン時ゲートウェイは OIC_BASE_URL とは異なるホストに 307 リダイレクトします。httpx はデフォルトでホスト間リダイレクト時に Authorization ヘッダーを削除するため、この既知の信頼できるホップでは手動処理によってヘッダーが保持されます。

ログ

ログは mcp_server.log に出力されます（MCP_LOG_FILE で上書き可能）。1ファイルあたり10MBで自動ローテーションされ、バックアップ5つを保持します（約60MB の上限）。無限に増えることはありません。logrotate、cron ジョブ、sudo はどのプラットフォームでも不要で、アプリが書き込みのたびに自分のログサイズを管理します。

環境ごとに1つのプロセスを実行する場合は、各 env ファイルに別々の MCP_LOG_FILE を設定して、ログを分離可能にしてください。

本番運用の堅牢化

• TLS（Nginx/Traefik などのリバースプロキシ）の背後で実行し、ネットワークアクセスを制限してください。WebSocket エンドポイントには独自の認証がないため、信頼できないネットワークに直接公開しないでください。

• 特別な理由がない限り、バインドアドレスは 127.0.0.1 のままにしてください。

• シークレットはボールトに保管し、.env をコミットしないでください。Linux では env ファイルを chmod 600 し、サービスユーザーが所有するようにしてください。

• OAuth クライアントには、必要な最小限のロールを割り当ててください（ServiceUser は読み取りレベル。ServiceDeveloper は作成/インポートツールが特に必要な場合を除いて避けてください）。

• プロセスマネージャー（systemd、launchd、NSSM）を使って再起動後にも生存させてください。オプションB を参照。

• 大規模なカタログではペイロードサイズに注意してください。全リストを取得するより、list_integrations_search で絞り込み語とページングを使う方が良いです。

トラブルシューティング

インストールと起動

• python または py が認識されない（Windows） - Python が「Add python.exe to PATH」なしでインストールされています。インストーラーを再実行して「変更」を選び、それを有効にするか、winget install -e --id Python.Python.3.12 で再インストールしてください。その後、新しいターミナルを開きます。

• running scripts is disabled on this system（Windows） - PowerShell の実行ポリシーが仮想環境のアクティブ化をブロックしています。Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned を実行するか、cmd.exe で .venv\Scripts\activate.bat を使用してください。

• ensurepip is not available（Debian/Ubuntu） - 独立した venv パッケージをインストールしてください: sudo apt install python3-venv。

• TypeError: unsupported operand type(s) for | - Python 3.9 以前を使用しています。3.10+ をインストールし、新しいインタプリタで仮想環境を再作成してください。

• 起動時に OIC_BASE_URL または OAUTH_* を指す ValidationError - env ファイルが見つからないか、不完全です。.env.example を .env にコピーしたこと、プロジェクトディレクトリからプロセスを開始したこと、OIC_ENV_FILE（設定している場合）が存在するファイルを指していることを確認してください。

• address already in use - 別のプロセスがポートを保持しています。lsof -i :8085（Linux/macOS）または netstat -ano | findstr :8085（Windows）で特定するか、別の PORT で起動してください。

認証

• トークンURLから401/403 - OAUTH_CLIENT_ID/OAUTH_CLIENT_SECRET と、OAUTH_TOKEN_URL が IDCS/IAM ドメインに対して正しいことを確認してください。

• トークンリクエストは成功する（200）のに、OIC の呼び出しがすべて401になる - これはほとんどの場合、トークンが原因ではなく IDCS ロールの欠落が原因です。OCI Console → Identity & Security → Domains → 自分のドメインで、OIC インスタンス自身のリソースアプリ（機密クライアントアプリではありません）を探し、Application roles → ServiceUser で自分の機密クライアントアプリをアプリケーションとして割り当ててください。割り当てた後、新しいトークンを取得してください。既存のトークンは遡ってロールを獲得しません。

接続

• 接続拒否/WebSocket に到達できない - サーバープロセスが実際に実行されているか（pgrep -af mcp_server.main、systemctl status oic-mcp、または Get-Service OicMcp）を確認し、同じポートに他のプロセスがバインドされていないことを確認してください。curl http://127.0.0.1:8085/healthz が最も手早い確認方法です。

• Claude Code がサーバーを「still connecting」と表示する、またはツールが読み込まれない - サーバーはクライアントセッションの開始前に起動してある必要があります。起動していなかった場合、自動的には再試行されません。サーバーの正常性を確認してから、クライアントを再起動してください。

• 別の環境のデータが返ってくる - 実 OS の環境変数が env ファイルを上書きしています。実 OS の環境変数の方が優先されるためです。env | grep OIC_（Linux/macOS）または Get-ChildItem Env:OIC_*（Windows）で確認し、シェルプロファイルから不要な古い値を消去してください。

ツールの使用

• 特定のフロー/デザインパスで 404 が発生する - 生のパス取得ではなく、デザインタイムのツール（get_integration_auto、summarize_*）を優先してください。バージョン解決と既知のエンドポイントの癖を処理してくれます。

• 応答が大きい、または遅い - 完全なカタログを取得するのではなく、list_integrations_search/search_integration_by_name とページング（perPage、maxPages）で絞り込んでください。

• ヘルスチェック - プロセス自体が起動していれば、GET /healthz は {"status": "ok"} を返します（OIC への接続は検証しません）。

ライセンス