ドキュメント

ゼロから接続まで

Local MCP Workspace の設定、接続チェーン全体の検証、Secure Tunnel の起動、よくある障害の診断をまとめた実践ガイドです。

インストールとマシン準備

デスクトップアプリは運用レイヤーを管理しますが、起動対象の Local MCP Runtime はマシンにインストールされている必要があります。

Tunnel Manager をインストール公開 Stable Release が利用可能になったら署名済み Windows Installer を使用してください。Landing Page と Release Endpoint は同じ Version Metadata を表示します。

MCP Runtime を準備対象 MCP Server に必要な Runtime をインストールします。Serena を使う Project では、Tunnel Manager の Environment から Serena コマンドを解決できることを確認してください。

Project はローカルに保持Source Project はマシン上に保持され、Tunnel Manager は Local MCP Process と Secure Tunnel 接続だけを調整します。

Profile を作成

Profile は1つの MCP Workspace 用の再利用可能な接続定義です。Validation と Runtime State を明確に保つため、Project/Runtime の組み合わせごとに1つの Profile を推奨します。

推奨 Profile 項目

Project FolderMCP Server が操作する Local Workspace。

MCP Target コマンドTunnel Manager が起動するコマンド。例：選択した Project 用の Serena MCP Server。

Tunnel Identity と Runtime KeyOpenAI Secure Tunnel Workflow 用に発行された値を使用し、機密値は Local Control Layer のみに保存してください。

Key 読み込み失敗のためだけに Profile を複製しないでください。保存済み Credential を修正し、既存 Profile を再 Validation します。

Start 前に Validation

Validation は必須の Preflight として扱います。Configuration、Credential、Tunnel Identity、MCP Target、Local Runtime がすべて合格してから Start を有効にします。

Profile configuration    PASS Runtime API key          PASS Tunnel ID                PASS MCP target               PASS Local runtime            READY

Process がすでに実行中なら、状態認識コントロールは二重 Start を防ぐべきです。別コピーを起動せず既存 Process を Stop または Restart してください。

ChatGPT を接続

Validation 合格後に Profile を Start すると、Tunnel Manager が設定済み Local MCP Process を起動し、Secure Tunnel を確立し、Desktop UI に接続状態を表示します。

Validation 済み Profile を StartMCP Runtime と Tunnel の両方が正常実行状態になるまで待ちます。

ChatGPT Connector 設定を開くTunnel に関連付けられた MCP Connector を選択または再接続します。

AI アクティビティを確認ChatGPT が Local MCP Tool を呼び出すと、Tunnel Manager は Connected/Standby から AI Active へ遷移し、対応する Runtime Log をストリーム表示します。

Serena Project 設定

Serena ベースの Project では、Project レベルの動作を Project の .serena ディレクトリに、マシン固有の Override を project.local.yml.

.serena/ ├── project.yml          # versioned project configuration └── project.local.yml    # machine-specific overrides

Trusted Project 要件

Serena が Project の activation_command を実行するのは、Project Path が Serena Global Configuration で Trusted の場合のみです。Global ルールではなく、正確な Project Path または限定した開発ディレクトリを Trust してください ** rule.

trusted_project_path_patterns: - /home/your-user/dev/your-project

トラブルシューティング

まず表示されている Validation 状態を確認し、その後 Streaming Log を調べます。問題は通常、接続チェーンの1レイヤーに絞れます。

API Key がない、または重複

新しい Key を追加する前に、Profile が保存済み Key を読み込んでいることを確認してください。Credential 変更後は再 Validation します。

Tunnel ID が無効

Tunnel が意図した Environment に属していることと、Profile が古い Identifier を再利用していないことを確認します。

Workspace が見つからない

MCP Runtime が実際に動くマシン上に Project Folder が存在することを確認します。Remote Linux Workspace はその Linux Host で有効な Path を使用してください。

Serena 未インストール、またはコマンドが見つからない

同じ User Environment で設定済み MCP Target を手動実行してください。PATH/Runtime を修正してから Tunnel Manager を再試行します。

Project が Trusted ではない

正確な Project Path を Serena Global の trusted_project_path_patternsに追加し、Serena/Tunnel Process を Restart して新しい Global Configuration を読み込みます。

Port が使用中

まず既存 Process を特定してください。Server の二重起動を避け、正常な Process を再利用するか、古い Process を Stop して Profile を Restart します。

Tunnel が切断

Local Network 到達性、Profile Credential、Tunnel 状態を確認します。Auto Recovery が有効なら Live Log で Reconnect の進行を確認してください。

ボタンが無効

現在の状態を確認します。Process が Starting または Running 中は Start を無効にし、互換性のない状態遷移中は Validate も利用できない場合があります。