Webship エンジニアリング

AIエージェントをWebshipのMCPサーバーに安全に接続する

TLS 1.3、強力なベアラートークン、ループバックバインディング、SSHトンネル、構成の検証、および実用的なインシデント対応チェックリストを使用して、Webship の隔離された MCP コントロールプレーンを設定します。

公開日 2026年9月10日

# AIエージェントをWebshipのMCPサーバーに安全に接続する

WebサーバーへのMCP接続はチャットウィジェットではありません。それは、運用状態を確認し、ルーティングやセキュリティポリシーを変更し、証明書をリロードし、静的リリースを有効化し、フリートの変更を調整し、署名されたWebshipアップデートをインストールできる運用インターフェースです。

それに応じて扱ってください：特権管理APIとして。最も安全なWebship設定は、MCPリスナーをパブリックデータプレーンからオフにし、ループバックにバインドし、TLS 1.3と強力なベアラートークンで保護し、認証済みSSHトンネルを通じてアクセスします。

このガイドはそのセットアップを構築し、各境界が存在する理由を説明し、利便性を危険に変えることなく操作するためのチェックリストを提供します。

信頼境界から始める

WebshipのパブリックトラフィックとMCPのトラフィックは別々のリスナーを使用します。MCPのコントロールプレーンはデフォルトで無効になっており、通常のHTTP、HTTP/2、HTTP/3、またはWebTransportリスナーと共有されることはありません。有効にすると、専用のTLS 1.3 HTTP/1.1エンドポイント経由でMCPを提供します。

安全なデプロイメントには4つの独立した制御があります：

ネットワーク到達性: MCP リスナーは 127.0.0.1 にバインドされており、パブリックまたはプライベートLANアドレスにはバインドされません。
通信の身元確認: クライアントは、信頼する認証局(CA)によって発行された証明書を検証します。
アプリケーション認証：すべてのリクエストには、1つの強力なベアラートークンが付与されます。
管理者アクセス: オペレーターは認証済みのSSHアカウントとトンネルを通じてループバックリスナーに接続します。

これらのコントロールのいずれも他のものを置き換えるものではありません。プライベートネットワーク経路のない TLS は、依然として認証の表面をさらします。証明書検証のないトンネルではエンドポイントの識別が曖昧になります。世界中に読み取り可能なファイル内のベアラートークンは、秘密ではありません。

証明書とトークンを準備する

内部CAから専用のMCP証明書を発行してください。下に示すトンネルについては、証明書のサブジェクト代替名にlocalhostおよび127.0.0.1を含め、その後発行元CAをMCPクライアントマシンの信頼ストアにインストールしてください。信頼エラーを不安全なTLSオプションで解決しないでください。

少なくとも32バイトの印字可能なASCII文字で、空白を含まないユニークなトークンを作成してください。32バイトのランダムな値を16進数でエンコードすると、64文字の安全な文字が得られます:

umask 077
openssl rand -hex 32

Webship は現在、保護された TOML 設定から直接 MCP トークンを読み取ります。token_file はサポートされていません。結果を Webship サービスアカウントとその管理グループのみが読み取れる設定ファイルに保存してください。トークンを systemd ユニット、シェル履歴、チケット、チャットメッセージ、または AI モデルに送信されるプロンプトに置かないでください。

典型的なDebianホストでは:

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

サービスユーザーとグループをあなたのインストール環境に合わせて調整してください。秘密鍵と設定は Webship が読み取れる必要がありますが、関連のないアカウントからは読み取れないようにしてください。

分離されたリスナーを有効にする

このセクションをアクティブな Webship 設定に追加してください:

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

空のallowed_ipsリストはエンドポイントを開きません。ループバッククライアントはデフォルトで引き続き許可されます。expose_remote = falseは意図された境界を明示します：後で誰かがlistenをループバック以外のアドレスに変更した場合、Webshipは制御プレーンを静かに公開するのではなく、設定を拒否します。

Webship は、TLSなし、トークンなし、短いトークンまたは空白を含むトークン、または証明書パスが空の有効な MCP リスナーも拒否します。公開プレースホルダートークンはリモートに公開される前に拒否されます。

再起動前に確認してください

MCP リスナー、TLS ID、およびトークンの変更はコントロールプレーンを再構築するため、プロセスの再起動が必要です。まず、完全な構成を検証してください:

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

リスナーがループバック上にのみ存在することを確認してください:

ss -ltn | grep '127.0.0.1:9443'

ホストのパブリックファイアウォールルールにポート9443を追加しないでください。次のステップではSSHを通じてアクセスします。

プライベートトンネルを作成する

管理者ワークステーションから、ローカルポートをWebshipのループバックリスナーに転送します:

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

MCP クライアントは現在 https://localhost:19443/mcp に接続します。TCP は SSH サーバーに到達し、SSH が接続をホストに転送し、ホストはループバック上の Webship への最終接続を開きます。SSH セッションを閉じると、その経路は直ちに削除されます。

キーを使用したSSH認証を使用し、どの管理者がトンネルを開けるかを制限し、通常のホストアクセス制御を適用してください。ジャンプホストが必要な場合は、MCP リスナーを Webship ホストのループバックインターフェース上に保持し、リスナーを広げるのではなくSSH経路を延長してください。

MCP クライアントを設定する

クライアントの設定形式は異なりますが、典型的なHTTP MCP エントリは次のようになります:

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

クライアントに保護された秘密の仕組みがある場合はそれを使用してください。そうでない場合は、クライアントの設定を現在のオペレーティングシステムのアカウントに制限してください。認可ヘッダーを付与するのはモデルではなくHTTPクライアントです。ライブトークンを会話に貼り付けてはいけません。

証明書の検証を有効にしたままにしてください。クライアントが証明書を拒否する場合は、証明書のサブジェクト代替名を修正するか、正しい内部CAをインストールしてください。恒久的なバイパスを追加しないでください。

最初のセッションを読み取り専用にする

トンネルとクライアントが接続された後、ディスカバリーと検査を開始します:

tools/list を求めてください。その応答は、実行中のリリースの権威ある引数スキーマです。
webship.get_config を呼び出し、現在の構成バージョンを記録してください。
該当する場合は、webship.reverse_proxy.get_status、webship.security.get_status、webship.ddos.get_status、およびwebship.tls.get_statusを点検してください。
ポリシーを変更する前に、webship.policy.explain または webship.security.simulate を使用してください。
返された設定がベアラートークンを編集していることを確認してください。

その後でのみ、非本番環境でミューテーションをテストします。Webship の構成ミューテーションには現在のバージョンIDが必要です。古い書き込みは、新しい変更を上書きするのではなく拒否されます。候補ポリシーは、アクティブ化前にシャドウ検証やトラフィックラボシナリオで確認できます。

Webship は、選択されたライブセキュリティのダウングレードも拒否します。MCP リクエストでは、アクティブな WAF、DDoS レイヤー、API シールド、ボットチャレンジ、エッジ認証ポリシー、またはレスポンスヘッダーレイヤーをオフにすることはできません。プロセスに紐づくリスナー、プロトコル、ワーカー、ランタイム、および MCP 認証の変更には、意図的な再起動が必要です。

それらの警備員はミスを減らすが、すべての許可された行動を無害にするわけではない。そのトークンは、更新やリリース操作を含む強力な制御面を提供する。提案されたツール呼び出しは、管理者のシェルコマンドを確認するのと同じように確認すること。

リモートバインディングが避けられない場合

ループバックプラスSSHが推奨される設計です。環境でプライベートネットワークリスナーが必要な場合は、例外を明示してください。

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

前の例のTLSブロックを保持し、プライベートDNS名に一致する証明書を使用し、ホストおよびネットワークのファイアウォールで同じ送信元範囲を適用してください。0.0.0.0/0や::/0を便利な許可リストとして使用してはいけません。アプリケーションの許可リストは実際にWebshipに到達する送信元アドレスを確認します。ロードバランサー、NATゲートウェイ、またはサービスメッシュがその前にある場合の挙動を確認してください。

リモートでのアクセスは、集中化されたアクセスログ、短い運用ウィンドウ、および迅速なローテーションの価値を高めます。それは単に MCP クライアントが別のマシンで動作しているから必要なものではありません。それこそがSSHトンネルが解決する問題です。

制御プレーンを意図的に操作する

このチェックリストを生産に使用してください:

エージェントやオペレーターが必要としない場合は、MCP を無効のままにしておいてください。
ループバックにバインドし、デフォルトでSSHトンネルを使用します。
専用のTLS識別情報を使用し、証明書の検証を有効のままにしてください。
各Webship環境に対してユニークなベアラートークンを生成してください。
ファイルシステムのアクセス権限でTOML、クライアント設定、TLSキー、およびSSHキーを保護してください。
開発、テスト、本番の資格情報を分ける。
変異を行う前に、ステータスとポリシーシミュレーションツールでセッションを開始します。
Webshipのセキュリティ監査イベントを保存および確認してください。
トークンを回転させ、被曝が疑われる場合はWebshipを再起動してください。
管理セッションが終了したらトンネルを閉じてください。

インシデント対応のために、アクティブなトンネルを閉じ、SSHアカウントを制限し、保護された TOML 内の MCP トークンを交換し、Webship を再起動し、最近のセキュリティ監査および構成バージョンの記録を確認してください。TLSの秘密鍵が漏洩している可能性がある場合は、同じ再起動の一環として新しい証明書と鍵を発行してください。その後、古いトークンをテストし、拒否されることを確認してください。

コントロールプレーンはコントロールプレーンのままであるべきです

MCP は、エージェントが実際の状態を検査し、検証済みの変更を適用できるため便利です。その操作を公開リクエスト経路を通さずに行うことが可能です。しかし、コントロールリスナーが別のインターネットエンドポイントになると、その利点は失われます。

境界をシンプルに保つ: 別のリスナー、ループバック接続の到達可能性、検証済みTLS、1つの保護されたベアラー認証情報、認証されたトンネル、バージョンがチェックされた変更、そして強力な操作に対する人間によるレビューのプロセス。Webship はプロトコルと安全ガードを提供する; オペレーターが誰がそれに到達できるかを決定する。

このガイドは、Webship 1.3.1 オペレータドキュメント、出荷時の構成例、MCP バリデーションおよびトランスポートコード、ランタイム構成ガード、ツールカタログに基づいています。他のリリースに適用する前に、現在の Webship ドキュメントおよび稼働中サーバーの tools/list レスポンスを確認してください。