OpenZiti Network Management

Ziti MCP サーバーは、安全なワークロードとエージェント型コンピューティング向けソリューションのポートフォリオの一環として、NetFoundry のスポンサーを受けています。 NetFoundry は、OpenZiti と zrok の開発元です。

MCP（Model Context Protocol） は、Anthropic が導入したオープンプロトコルで、LLM が外部のツール、リソース、リモートサービスと通信する方法を標準化します。

Ziti MCP サーバーは LLM や AI エージェントと連携し、自然言語を使ってさまざまな Ziti ネットワーク管理操作を実行できます。たとえば、Claude Desktop に次のように尋ねるだけで、Ziti の管理操作を実行できます。

• どの ID が存在するか一覧表示してください

• ネットワークに公開されているものがあるか教えてください

• 設定ミスの可能性はありますか？

• Demo1 サービスにアクセスできる ID はどれですか？

• 「Demo」という名前の新しい Ziti ID を作成して、その ID を取得してください

• UPDB を使って本番環境の Ziti ネットワークにログインしてください

• ステージングネットワークに切り替えてください

• など

🚀 はじめに

前提条件：

• Claude Desktop またはその他の MCP クライアント
• OpenZiti ネットワーク
• Go 1.24+（ソースからビルドする場合のみ）

インストール

ビルド済みバイナリをダウンロードする

macOS、Linux、Windows（amd64 および arm64）向けのビルド済みバイナリは、リリースページで入手できます。

macOS（Apple Silicon）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_darwin_arm64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

macOS（Intel）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_darwin_amd64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

Linux（amd64）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_linux_amd64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

Linux（arm64）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_linux_arm64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

Windows

リリースページから適切な .zip をダウンロードし、展開した ziti-mcp-server.exe を PATH に追加してください。

ソースからビルドする

go install github.com/openziti/ziti-mcp-server/cmd/ziti-mcp-server@latest

AI クライアントに登録する

install を使って、Ziti MCP サーバーを AI クライアントに登録します。この操作で更新されるのはクライアントの設定ファイルのみで、認証は行われません。認証には、実行時のログインツールまたは init を使用してください。

# Register with Claude Desktop (default)
ziti-mcp-server install

# Register with a specific client
ziti-mcp-server install --client claude-code
ziti-mcp-server install --client cursor
ziti-mcp-server install --client windsurf
ziti-mcp-server install --client vscode
ziti-mcp-server install --client warp

# Register with read-only tools only
ziti-mcp-server install --read-only

# Register with specific tool patterns
ziti-mcp-server install --tools '*Identit*,list*'

インストール後、AI クライアントを再起動し、実行時のログインツールを使って認証してください（例：「ctrl.example.com の Ziti ネットワークに、ユーザー名 admin でログインしてください」と尋ねます）。

起動してログインする

サーバーは事前設定なしで起動できます。AI エージェントは、組み込みのログインツールを使って実行時にネットワークへログインできます。

ziti-mcp-server run

その後、AI クライアントで次のように尋ねるだけです。

ユーザー名 admin、パスワード admin で、192.168.1.100:1280 の Ziti ネットワークにログインしてください

対話形式ではない環境や自動化された環境では、起動前に認証情報を事前設定するために init を使用してください。

ziti-mcp-server init \
  --auth-mode updb \
  --ziti-controller-host <your-controller-host> \
  --username <username> \
  --password <password> \
  --profile prod

サポートされているすべてのモード（UPDB、デバイス認証、クライアント認証情報、ID ファイル）については、認証を参照してください。

クライアントの手動設定

install コマンドでクライアント設定を自動的に行えます。MCP クライアントを手動で設定する必要がある場合は、設定に次の内容を追加して再起動してください。

{
  "mcpServers": {
    "ziti": {
      "command": "/path/to/ziti-mcp-server",
      "args": ["run"],
      "capabilities": ["tools"],
      "env": {
        "OPENZITI_MCP_DEBUG": "true"
      }
    }
  }
}

使用できるツールを制御するには、args 配列に --tools '<pattern>' および／または --read-only を追加できます。ツールアクセスの制限を参照してください。

統合を確認する

MCP クライアント（Claude Desktop、Windsurf、Cursor、Warp など）を再起動し、Ziti ネットワークの管理を手伝うよう依頼します。

🕸️ アーキテクチャ

Ziti MCP Server は Model Context Protocol を実装しており、クライアント（Claude など）が次の操作を行えるようにします。

1. 利用可能な Ziti ツールの一覧を要求する
2. パラメーターを指定して特定のツールを呼び出す
3. Ziti Management API から構造化された応答を受け取る

サーバーは、認証、リクエストの検証、Ziti Management API との安全な通信を処理します。

メモ

サーバーはローカルプロセスとして動作し、Claude Desktop に接続します。これにより、Ziti の認証情報を公開せずに安全な通信を実現できます。

🔐 認証

Ziti MCP Server は Ziti Management API を使用し、Ziti ネットワークにアクセスするための認証が必要です。

認証モード

サーバーは 4 つの認証モードをサポートしています。

UPDB モード（ユーザー名／パスワード）

Ziti コントローラーに対して、ユーザー名とパスワードで直接認証する場合に使用します。

ziti-mcp-server init \
  --auth-mode updb \
  --ziti-controller-host <your-controller-host> \
  --username <username> \
  --password <password>

または、実行時に AI エージェントから loginUpdb ツールを使用します。

Device Auth モード（対話型ログイン）

ブラウザーを使用した対話型ログインに使用します。開発環境やユーザー向けのシナリオにおすすめです。

ziti-mcp-server init \
  --auth-mode device-auth \
  --ziti-controller-host <your-controller-host> \
  --idp-domain <your-idp-domain> \
  --idp-client-id <your-client-id> \
  --idp-audience <your-audience>

または、実行時に loginDeviceAuth ツールを使用します（ユーザー向けの確認 URL が返され、その後 completeLogin で完了します）。

Client Credentials モード（サービスアカウント）

サービスアカウントや自動化に使用します。本番環境におすすめです。

メモ

セキュリティリスクを軽減するため、トークンの有効期間はできる限り短くしてください。詳細はこちら

ziti-mcp-server init \
  --auth-mode client-credentials \
  --ziti-controller-host <your-controller-host> \
  --idp-domain <your-idp-domain> \
  --idp-client-id <your-client-id> \
  --idp-client-secret <your-client-secret>

Identity File モード（mTLS 証明書）

Ziti の ID JSON ファイルを使用した証明書ベースの認証に使用します。IdP の設定は不要です。

ziti-mcp-server init \
  --auth-mode identity \
  --identity-file <path-to-identity.json>

ID ファイルは、ztAPI、id.cert、id.key、id.ca フィールドを含む標準的な Ziti ID JSON ファイルです。証明書情報は抽出され、設定ファイルに保存されます。init が正常に完了した後は、必要に応じて追加のセキュリティ対策として ID ファイルを削除できます。

重要

CLI の init を使用する場合は、次のときに毎回実行する必要があります。

• MCP Server を初めて設定するとき
• 前回のセッションからログアウトしたとき
• 別の Ziti ネットワークに切り替えるとき
• トークンの有効期限が切れたとき

代わりに、実行時のログインツール（loginUpdb など）を使用すれば、サーバーを再起動せずに認証できます。

複数プロファイルのサポート

サーバーは複数の名前付きネットワークプロファイルをサポートしているため、複数の Ziti ネットワークを同時に管理できます。

# Pre-configure two profiles
ziti-mcp-server init --auth-mode updb --profile prod ...
ziti-mcp-server init --auth-mode updb --profile staging ...

# Start with a specific profile active
ziti-mcp-server run --profile prod

実行時に AI エージェントは、次の操作を行えます。

• loginUpdb、loginIdentity などを使用して追加のネットワークにログインする
• listNetworks を使用してすべてのネットワークを一覧表示する
• selectNetwork を使用してネットワークを切り替える
• logout を使用してネットワークからログアウトする

認証情報は、アクセス許可 0600 で ~/.config/ziti-mcp-server/config.json に保存されます。

セッション管理

現在の認証セッションに関する情報を表示するには、次のコマンドを実行します。

ziti-mcp-server session
ziti-mcp-server session --profile prod

ログアウト

ziti-mcp-server logout
ziti-mcp-server logout --profile prod

または、実行時に AI エージェントから logout ツールを使用します。

🛠️ サポートされている MCP ツール

Ziti MCP Server は、自然言語で Ziti ネットワークを管理するための 201 個の Ziti API ツールと 8 個のメタツールを提供します。ツールはリソースの種類ごとに整理されています。

ヒント： --read-only または --tools のパターンを使用すると、必要なツールだけを公開できます。ツールアクセスの制限を参照してください。

メタツール（ネットワーク管理）

これらのツールは、--tools や --read-only によるフィルタリングに関係なく、常に利用できます。

ツール	説明
loginUpdb	ユーザー名とパスワードによる認証を使用して接続します
loginIdentity	Ziti の ID JSON（mTLS 証明書）を使用して接続します
loginClientCredentials	OAuth2 クライアント認証情報を使用して接続します
loginDeviceAuth	OAuth2 デバイス認証フローを開始します（確認用 URL を返します）
completeLogin	ブラウザーで承認した後、保留中のデバイス認証ログインを完了します
logout	Ziti ネットワークから切断します（プロファイルの認証情報を消去します）
listNetworks	設定済みのすべてのネットワークプロファイルと接続状態を一覧表示します
selectNetwork	アクティブなネットワークプロファイルを切り替えます

ツールのカテゴリ

カテゴリ	ツール	説明
ID	22	CRUD、関連付け、ライフサイクル、ポスチャ、トレース
サービス	12	CRUD と関連付けのクエリ
エッジルーター	11	CRUD、関連付け、再登録
エッジルーターポリシー	7	CRUD と関連付けのクエリ
サービスエッジルーターポリシー	7	CRUD と関連付けのクエリ
サービスポリシー	8	CRUD と関連付け（Dial/Bind）
設定	6	CRUD とサービス関連付け
設定タイプ	6	CRUD と設定のクエリ
認証ポリシー	5	CRUD（プライマリ／セカンダリ認証設定）
認証子	5	CRUD（updb／証明書）
認証局	7	CRUD、JWT の取得、検証
外部 JWT 署名者	5	外部 JWT 署名者の CRUD
ポスチャチェック	8	CRUD、タイプ、ロール属性
ルーター	5	ファブリックルーターの CRUD
トランジットルーター	5	トランジットルーターの CRUD
ターミネーター	5	ターミネーターの CRUD
登録	5	CRUD と更新
コントローラー設定	6	CRUD と有効値のクエリ
コントローラーとシステム情報	4	バージョン、機能、概要
セッションと API セッション	6	一覧、詳細、削除
ID タイプ	2	一覧と詳細
ファブリック（ルーター、サービス、…）	34	ファブリック層の CRUD、回線、リンク、クラスター、DB スナップショット

詳細な表とプロンプト例を含むツールの完全なリファレンスについては、docs/tools.md を参照してください。

プロンプトの例

• Show me all Ziti identities
• Which identities have access to the Demo1 service?
• Create a new identity called 'demo-admin' and make it an admin
• List all edge routers and their status
• Show me all Dial service policies
• What version is the Ziti controller running?
• Give me a summary of the network — how many identities, services, and routers exist?
• Create a Bind policy for the 'my-api' service

🔒 セキュリティ

ツールアクセスの制限

Ziti MCP サーバーを設定する際は、特定のニーズに応じてツールアクセスを制限してください。

# Enable only read-only operations
ziti-mcp-server run --read-only

# Alternative way to enable only read-only operations
ziti-mcp-server run --tools 'list*,get*'

# Limit to just identity-related tools
ziti-mcp-server run --tools '*Identit*'

# Limit to read-only identity-related tools
ziti-mcp-server run --tools '*Identit*' --read-only

# Run the server with all tools enabled
ziti-mcp-server run --tools '*'

重要

--read-only と --tools の両方のフラグを同時に使用する場合、セキュリティのため --read-only フラグが優先されます。メタツール（login、logout、listNetworks、selectNetwork）は、フィルタリングに関係なく常に利用できます。

この方法には、次のような重要な利点があります。

1. セキュリティの強化：利用可能なツールを制限することで、潜在的な攻撃対象領域を縮小できます。
2. パフォーマンスの向上：ツールが少ないほど、ツールの推論に使用するコンテキストウィンドウを節約できます。
3. リソースベースのアクセス制御：異なるツールセットを使用する複数のインスタンスを設定できます。
4. 監査の簡素化：実行された操作を追跡しやすくなります。

認証情報の保存

• 認証情報は、アクセス権限 0600 で ~/.config/ziti-mcp-server/config.json に保存されます。
• 設定ファイルは、誰でも読み取り可能な状態にはなりません。
• 認証では、OAuth 2.0 デバイス認可、クライアント認証情報、mTLS 証明書、UPDB がサポートされています。
• logout コマンドまたはツールを使用して、認証情報を簡単に削除できます。

重要

セキュリティのベストプラクティスとして、セッションを終了するとき、またはネットワークを切り替えるときは、必ずログアウトしてください。

注意

認証プロセス中に要求される権限を必ず確認し、セキュリティ要件に合致していることを確かめてください。

セキュリティスキャン

プロトコルレベルのリスクを検出するために開発された、コミュニティツールを使用した定期的なサーバーのスキャンを推奨します。

• mcpscan.ai — MCP エンドポイント向けのウェブベーススキャナー
• mcp-scan — サーバーの動作を評価する CLI ツール

問題の報告

フィードバックの提供やバグの報告は、イシュートラッカーで問題を報告してください。

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

利用可能なコマンドとオプションをすべて確認して、トラブルシューティングを始めましょう。

ziti-mcp-server help

🚨 よくある問題

1. 認証の失敗

   • Ziti ネットワークで適切な権限があることを確認してください。
   • ziti-mcp-server init --auth-mode <mode> ... で再初期化してみてください。
   • または、実行時ログインツールを使用して再認証してください。

2. TLS 証明書エラー

   • サーバーはログイン時に EST /cacerts エンドポイント経由でコントローラーの CA を自動取得します。
   • CA の取得に失敗した場合は、コントローラーの CA をシステムの信頼ストアに追加してください。
   • または、再ログインして CA を再取得してください。

3. クライアントがサーバーに接続できない

   • 設定を変更した後、MCP クライアントを再起動してください。
   • クライアント設定のバイナリパスが正しいことを確認してください。

4. 無効な設定エラー

   • 通常、アクティブなプロファイルがないか、認証情報が不足している場合に発生します。
   • listNetworks を使用してプロファイルの状態を確認してください。
   • ログインツールまたは ziti-mcp-server init を使用して認証してください。

ヒント

接続の問題のほとんどは、サーバーと MCP クライアントの両方を再起動することで解決できます。

📋 デバッグログ

詳細なログを表示するには、デバッグモードを有効にしてください。

export OPENZITI_MCP_DEBUG=true

Claude Desktop から詳細な MCP クライアントログを取得します。

# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

👨‍💻 開発

ソースからのビルド

# Clone the repository
git clone https://github.com/openziti/ziti-mcp-server.git
cd ziti-mcp-server-go

# Build
go build ./cmd/ziti-mcp-server

# Run
./ziti-mcp-server run

API クライアントの再生成

internal/gen/ の Ziti API クライアントは、go-swagger を使用して OpenAPI 仕様から生成されます。

make generate