{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/readme-banner.png\" alt=\"OpenZiti MCP Server Banner\">\n</p>\n<div align=\"center\">\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Go Version](https://img.shields.io/badge/go-%3E%3D1.24-blue.svg)](https://go.dev/)\n\n</div>\n\n<div align=\"center\">\n\n🚀 [Getting Started](#-getting-started) • 🕸️ [Architecture](#%EF%B8%8F-architecture) • 🔐 [Authentication](#-authentication) • 🛠️ [Supported Tools](#%EF%B8%8F-supported-mcp-tools) • 🔒 [Security](#-security) • 🩺 [Troubleshooting](#-troubleshooting) • 📋 [Debug Logs](#-debug-logs) • 👨‍💻 [Development](#-development)\n\n</div>\n\nThe Ziti MCP Server is sponsored by [NetFoundry](https://netfoundry.io) as part of its portfolio of solutions\nfor secure workloads and agentic computing.\nNetFoundry is the creator of [OpenZiti](https://netfoundry.io/docs/openziti/)\nand [zrok](https://netfoundry.io/docs/zrok/getting-started).\n\n[MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) is an open protocol introduced by Anthropic that standardizes how large language models communicate with external tools, resources or remote services.\n\nThe Ziti MCP Server integrates with LLMs and AI agents, allowing you to perform various Ziti network management operations using natural language. For instance, you could simply ask Claude Desktop to perform Ziti management operations:\n\n- > List which identities exist\n- > Tell me if there are any exposures in the network\n- > Do you see potential misconfigurations?\n- > Which identities have access to the Demo1 service?\n- > Create a new Ziti identity named \"Demo\" and get its ID\n- > Log into my prod Ziti network using UPDB\n- > Switch to the staging network\n- > etc.\n\n<br/>\n\n## 🚀 Getting Started\n\n**Prerequisites:**\n\n- [Claude Desktop](https://claude.ai/download) or any other [MCP Client](https://modelcontextprotocol.io/clients)\n- [OpenZiti](https://openziti.io/) network\n- [Go 1.24+](https://go.dev/dl/) (only if building from source)\n\n<br/>\n\n### Install\n\n#### Download a pre-built binary\n\nPre-built binaries are available for macOS, Linux, and Windows (amd64 and arm64) on the [releases page](https://github.com/openziti/ziti-mcp-server/releases).\n\n**macOS (Apple Silicon)**\n\n```bash\ncurl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_darwin_arm64.tar.gz | tar xz\nsudo mv ziti-mcp-server /usr/local/bin/\n```\n\n**macOS (Intel)**\n\n```bash\ncurl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_darwin_amd64.tar.gz | tar xz\nsudo mv ziti-mcp-server /usr/local/bin/\n```\n\n**Linux (amd64)**\n\n```bash\ncurl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_linux_amd64.tar.gz | tar xz\nsudo mv ziti-mcp-server /usr/local/bin/\n```\n\n**Linux (arm64)**\n\n```bash\ncurl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_linux_arm64.tar.gz | tar xz\nsudo mv ziti-mcp-server /usr/local/bin/\n```\n\n**Windows**\n\nDownload the appropriate `.zip` from the [releases page](https://github.com/openziti/ziti-mcp-server/releases) and add the extracted `ziti-mcp-server.exe` to your PATH.\n\n#### Build from source\n\n```bash\ngo install github.com/openziti/ziti-mcp-server/cmd/ziti-mcp-server@latest\n```\n\n### Register with your AI Client\n\nUse `install` to register the Ziti MCP Server with your AI client. This only updates the client's configuration file — it does **not** authenticate. Use the runtime login tools or `init` for that.\n\n```bash\n# Register with Claude Desktop (default)\nziti-mcp-server install\n\n# Register with a specific client\nziti-mcp-server install --client claude-code\nziti-mcp-server install --client cursor\nziti-mcp-server install --client windsurf\nziti-mcp-server install --client vscode\nziti-mcp-server install --client warp\n\n# Register with read-only tools only\nziti-mcp-server install --read-only\n\n# Register with specific tool patterns\nziti-mcp-server install --tools '*Identit*,list*'\n```\n\nAfter installing, restart your AI client and use the runtime login tools to authenticate (e.g., ask: _\"Log into my Ziti network at ctrl.example.com with username admin\"_).\n\n### Start and Log In\n\nThe server can start with **no prior configuration**. The AI agent can log into networks at runtime using the built-in login tools:\n\n```bash\nziti-mcp-server run\n```\n\nThen in your AI client, simply ask:\n\n> Log into my Ziti network at 192.168.1.100:1280 with username admin and password admin\n\nFor non-interactive or automated setups, use `init` to pre-configure credentials before starting:\n\n```bash\nziti-mcp-server init \\\n  --auth-mode updb \\\n  --ziti-controller-host <your-controller-host> \\\n  --username <username> \\\n  --password <password> \\\n  --profile prod\n```\n\nSee [Authentication](#-authentication) for all supported modes (UPDB, device auth, client credentials, identity file).\n\n### Manual Client Configuration\n\nThe `install` command handles client configuration automatically. If you need to configure an MCP client manually, add this to its configuration and restart:\n\n```json\n{\n  \"mcpServers\": {\n    \"ziti\": {\n      \"command\": \"/path/to/ziti-mcp-server\",\n      \"args\": [\"run\"],\n      \"capabilities\": [\"tools\"],\n      \"env\": {\n        \"OPENZITI_MCP_DEBUG\": \"true\"\n      }\n    }\n  }\n}\n```\n\nYou can add `--tools '<pattern>'` and/or `--read-only` to the args array to control which tools are available. See [Restricting Tool Access](#restricting-tool-access).\n\n### Verify your integration\n\nRestart your MCP Client (Claude Desktop, Windsurf, Cursor, Warp, etc.) and ask it to help you manage your Ziti network.\n\n## 🕸️ Architecture\n\nThe Ziti MCP Server implements the Model Context Protocol, allowing clients (like Claude) to:\n\n1. Request a list of available Ziti tools\n2. Call specific tools with parameters\n3. Receive structured responses from the Ziti Management API\n\nThe server handles authentication, request validation, and secure communication with the Ziti Management API.\n\n<div align=\"center\">\n  <img src=\"assets/arch.jpg\" alt=\"Ziti MCP Server\" width=\"800\">\n</div>\n\n> [!NOTE]\n> The server operates as a local process that connects to Claude Desktop, enabling secure communication without exposing your Ziti credentials.\n\n## 🔐 Authentication\n\nThe Ziti MCP Server uses the Ziti Management API and requires authentication to access your Ziti network.\n\n### Authentication Modes\n\nThe server supports four authentication modes:\n\n#### UPDB Mode (Username/Password)\n\nUse this mode for direct username/password authentication against the Ziti controller:\n\n```bash\nziti-mcp-server init \\\n  --auth-mode updb \\\n  --ziti-controller-host <your-controller-host> \\\n  --username <username> \\\n  --password <password>\n```\n\nOr at runtime via the AI agent using the `loginUpdb` tool.\n\n#### Device Auth Mode (Interactive Login)\n\nUse this mode for interactive browser-based login. Recommended for development and user-facing scenarios:\n\n```bash\nziti-mcp-server init \\\n  --auth-mode device-auth \\\n  --ziti-controller-host <your-controller-host> \\\n  --idp-domain <your-idp-domain> \\\n  --idp-client-id <your-client-id> \\\n  --idp-audience <your-audience>\n```\n\nOr at runtime via the `loginDeviceAuth` tool (returns a verification URL for the user, then `completeLogin` to finish).\n\n#### Client Credentials Mode (Service Account)\n\nUse this mode for service accounts and automation. Recommended for production environments:\n\n> [!NOTE]\n> Keep the token lifetime as minimal as possible to reduce security risks. [See more](https://auth0.com/docs/secure/tokens/access-tokens/update-access-token-lifetime)\n\n```bash\nziti-mcp-server init \\\n  --auth-mode client-credentials \\\n  --ziti-controller-host <your-controller-host> \\\n  --idp-domain <your-idp-domain> \\\n  --idp-client-id <your-client-id> \\\n  --idp-client-secret <your-client-secret>\n```\n\n#### Identity File Mode (mTLS Certificate)\n\nUse this mode for certificate-based authentication with a Ziti identity JSON file. No IdP configuration is needed:\n\n```bash\nziti-mcp-server init \\\n  --auth-mode identity \\\n  --identity-file <path-to-identity.json>\n```\n\nThe identity file is a standard Ziti identity JSON file containing `ztAPI`, `id.cert`, `id.key`, and `id.ca` fields. The certificate material is extracted and stored in the config file. The identity file may be deleted after a successful `init` (for additional security, if desired).\n\n> [!IMPORTANT]\n>\n> When using CLI `init`, it needs to be run whenever:\n>\n> - You're setting up the MCP Server for the first time\n> - You've logged out from a previous session\n> - You want to switch to a different Ziti network\n> - Your token has expired\n>\n> Alternatively, use the runtime login tools (`loginUpdb`, etc.) to authenticate without restarting the server.\n\n### Multi-Profile Support\n\nThe server supports multiple named network profiles, allowing you to manage several Ziti networks simultaneously:\n\n```bash\n# Pre-configure two profiles\nziti-mcp-server init --auth-mode updb --profile prod ...\nziti-mcp-server init --auth-mode updb --profile staging ...\n\n# Start with a specific profile active\nziti-mcp-server run --profile prod\n```\n\nAt runtime, the AI agent can:\n- **Log into additional networks** using `loginUpdb`, `loginIdentity`, etc.\n- **List all networks** using `listNetworks`\n- **Switch between networks** using `selectNetwork`\n- **Log out** from a network using `logout`\n\nCredentials are stored in `~/.config/ziti-mcp-server/config.json` with 0600 permissions.\n\n### Session Management\n\nTo see information about your current authentication session:\n\n```bash\nziti-mcp-server session\nziti-mcp-server session --profile prod\n```\n\n### Logging Out\n\n```bash\nziti-mcp-server logout\nziti-mcp-server logout --profile prod\n```\n\nOr at runtime via the AI agent using the `logout` tool.\n\n## 🛠️ Supported MCP Tools\n\nThe Ziti MCP Server provides **201 Ziti API tools** plus **8 meta-tools** for managing your Ziti network through natural language. Tools are organized by resource type.\n\n> **Tip:** Use `--read-only` or `--tools` patterns to expose only the tools you need. See [Restricting Tool Access](#restricting-tool-access).\n\n### Meta-Tools (Network Management)\n\nThese tools are always available regardless of `--tools` or `--read-only` filtering.\n\n| Tool                     | Description                                                                                      |\n| ------------------------ | ------------------------------------------------------------------------------------------------ |\n| `loginUpdb`              | Connect using username/password authentication                                                   |\n| `loginIdentity`          | Connect using a Ziti identity JSON (mTLS certificate)                                            |\n| `loginClientCredentials` | Connect using OAuth2 client credentials                                                          |\n| `loginDeviceAuth`        | Start OAuth2 device auth flow (returns verification URL)                                         |\n| `completeLogin`          | Complete a pending device-auth login after browser approval                                      |\n| `logout`                 | Disconnect from a Ziti network (clear profile credentials)                                       |\n| `listNetworks`           | List all configured network profiles with connection status                                      |\n| `selectNetwork`          | Switch the active network profile                                                                |\n\n### Tool Categories\n\n| Category                      | Tools | Description                                               |\n| ----------------------------- | ----: | --------------------------------------------------------- |\n| Identities                    |    22 | CRUD, relationships, lifecycle, posture, tracing          |\n| Services                      |    12 | CRUD and relationship queries                             |\n| Edge Routers                  |    11 | CRUD, relationships, re-enrollment                        |\n| Edge Router Policies          |     7 | CRUD and relationship queries                             |\n| Service Edge Router Policies  |     7 | CRUD and relationship queries                             |\n| Service Policies              |     8 | CRUD and relationships (Dial/Bind)                        |\n| Configs                       |     6 | CRUD and service relationships                            |\n| Config Types                  |     6 | CRUD and config queries                                   |\n| Auth Policies                 |     5 | CRUD (primary/secondary auth settings)                    |\n| Authenticators                |     5 | CRUD (updb/cert)                                          |\n| Certificate Authorities       |     7 | CRUD, JWT retrieval, verification                         |\n| External JWT Signers          |     5 | CRUD for external JWT signers                             |\n| Posture Checks                |     8 | CRUD, types, and role attributes                          |\n| Routers                       |     5 | CRUD for fabric routers                                   |\n| Transit Routers               |     5 | CRUD for transit routers                                  |\n| Terminators                   |     5 | CRUD for terminators                                      |\n| Enrollments                   |     5 | CRUD and refresh                                          |\n| Controller Settings           |     6 | CRUD and effective value queries                          |\n| Controllers & System Info     |     4 | Version, capabilities, summary                            |\n| Sessions & API Sessions       |     6 | List, detail, delete                                      |\n| Identity Types                |     2 | List and detail                                           |\n| Fabric (Routers, Services, …) |    34 | Fabric-layer CRUD, circuits, links, cluster, DB snapshots |\n\n> See **[docs/tools.md](docs/tools.md)** for the full tool reference with detailed tables and example prompts.\n\n### Example Prompts\n\n- `Show me all Ziti identities`\n- `Which identities have access to the Demo1 service?`\n- `Create a new identity called 'demo-admin' and make it an admin`\n- `List all edge routers and their status`\n- `Show me all Dial service policies`\n- `What version is the Ziti controller running?`\n- `Give me a summary of the network — how many identities, services, and routers exist?`\n- `Create a Bind policy for the 'my-api' service`\n\n## 🔒 Security\n\n### Restricting Tool Access\n\nWhen configuring the Ziti MCP Server, limit tool access based on your specific needs:\n\n```bash\n# Enable only read-only operations\nziti-mcp-server run --read-only\n\n# Alternative way to enable only read-only operations\nziti-mcp-server run --tools 'list*,get*'\n\n# Limit to just identity-related tools\nziti-mcp-server run --tools '*Identit*'\n\n# Limit to read-only identity-related tools\nziti-mcp-server run --tools '*Identit*' --read-only\n\n# Run the server with all tools enabled\nziti-mcp-server run --tools '*'\n```\n\n> [!IMPORTANT]\n> When both `--read-only` and `--tools` flags are used together, the `--read-only` flag takes priority for security. Meta-tools (login, logout, listNetworks, selectNetwork) are always available regardless of filtering.\n\nThis approach offers several important benefits:\n\n1. **Enhanced Security**: Limiting available tools reduces the potential attack surface.\n2. **Better Performance**: Fewer tools means less context window usage for tool reasoning.\n3. **Resource-Based Access Control**: Configure different instances with different tool sets.\n4. **Simplified Auditing**: Easier to track which operations were performed.\n\n### Credential Storage\n\n- Credentials are stored in `~/.config/ziti-mcp-server/config.json` with 0600 permissions\n- The config file is never world-readable\n- Authentication supports OAuth 2.0 device authorization, client credentials, mTLS certificates, and UPDB\n- Easy credential removal via `logout` command or tool\n\n> [!IMPORTANT]\n> For security best practices, always log out when you're done with a session or switching between networks.\n\n> [!CAUTION]\n> Always review the permissions requested during the authentication process to ensure they align with your security requirements.\n\n### Security Scanning\n\nWe recommend regularly scanning this server with community tools built to surface protocol-level risks:\n\n- **[mcpscan.ai](https://mcpscan.ai)** — Web-based scanner for MCP endpoints\n- **[mcp-scan](https://github.com/invariantlabs-ai/mcp-scan)** — CLI tool for evaluating server behavior\n\n### Reporting Issues\n\nTo provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/openziti/ziti-mcp-server/issues).\n\n## 🩺 Troubleshooting\n\nStart troubleshooting by exploring all available commands and options:\n\n```bash\nziti-mcp-server help\n```\n\n### 🚨 Common Issues\n\n1. **Authentication Failures**\n   - Ensure you have the correct permissions in your Ziti network\n   - Try re-initializing with `ziti-mcp-server init --auth-mode <mode> ...`\n   - Or use the runtime login tools to re-authenticate\n\n2. **TLS Certificate Errors**\n   - The server auto-fetches the controller's CA on login via the EST `/cacerts` endpoint\n   - If the CA fetch fails, add the controller CA to your system trust store\n   - Or re-login to trigger a fresh CA fetch\n\n3. **Client Can't Connect to the Server**\n   - Restart your MCP client after configuration changes\n   - Check that the binary path in the client config is correct\n\n4. **Invalid Configuration Error**\n   - This typically happens when no profile is active or credentials are missing\n   - Use `listNetworks` to check profile status\n   - Use a login tool or `ziti-mcp-server init` to authenticate\n\n> [!TIP]\n> Most connection issues can be resolved by restarting both the server and your MCP client.\n\n## 📋 Debug logs\n\nEnable debug mode to view detailed logs:\n\n```sh\nexport OPENZITI_MCP_DEBUG=true\n```\n\nGet detailed MCP Client logs from Claude Desktop:\n\n```sh\n# Follow logs in real-time\ntail -n 20 -F ~/Library/Logs/Claude/mcp*.log\n```\n\n## 👨‍💻 Development\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/openziti/ziti-mcp-server.git\ncd ziti-mcp-server-go\n\n# Build\ngo build ./cmd/ziti-mcp-server\n\n# Run\n./ziti-mcp-server run\n```\n\n### Regenerating API Clients\n\nThe Ziti API clients in `internal/gen/` are generated from OpenAPI specs using go-swagger:\n\n```bash\nmake generate\n```\n",
  "bytes": 18575,
  "sha": "5583508ef9ed3118060f95b4c50559e176c16b67460a2291538b5958bad1eefd",
  "repo_slug": "openziti/ziti-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_openziti_ziti_mcp_server_e9355a1e/readme"
}