@openziti/ziti-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,868 @@
+<p align="center">
+  <img src="assets/readme-banner.png" alt="OpenZiti MCP Server Banner">
+</p>
+<div align="center">
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![NPM Downloads](https://img.shields.io/npm/dw/%40openziti%2Fziti-mcp-server)](https://www.npmjs.com/package/@openziti/ziti-mcp-server)
+[![NPM Version](https://img.shields.io/npm/v/@openziti/ziti-mcp-server)](https://www.npmjs.com/package/@openziti/ziti-mcp-server)
+
+</div>
+
+<div align="center">
+
+🚀 [Getting Started](#-getting-started) • 🕸️ [Architecture](#%EF%B8%8F-architecture) • 🔐 [Authentication](#-authentication) • 🛠️ [Supported Tools](#%EF%B8%8F-supported-tools) • 🩺 [Troubleshooting](#-troubleshooting) • 📋 [Debug Logs](#-debug-logs) • 👨‍💻 [Development](#-development) • 🔒 [Security](#-security)
+
+</div>
+
+[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.
+
+The 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:
+
+- > List which identities exist
+- > Which identities have access to the Demo1 service
+- > Create a new Ziti identity named "Demo" and get its ID
+- > etc.
+
+<br/>
+
+## 🚀 Getting Started
+
+**Prerequisites:**
+
+- [Node.js v18 or higher](https://nodejs.org/en/download)
+- [Claude Desktop](https://claude.ai/download) or any other [MCP Client](https://modelcontextprotocol.io/clients)
+- An IdP account with appropriate permissions ([Auth0](https://auth0.com/) can be used as the IdP)
+- [OpenZiti](https://openziti.io/) network
+
+<br/>
+
+### Install the Ziti MCP Server
+
+Install Ziti MCP Server and configure it to work with your preferred MCP Client. The `--tools` parameter specifies which tools should be available (defaults to `*` if not provided).
+
+**Claude Desktop with all tools**
+
+```bash
+npx @openziti/ziti-mcp-server init
+```
+
+**Claude Desktop with read-only tools**
+
+```bash
+npx @openziti/ziti-mcp-server init --read-only
+```
+
+You can also explicitly select read-only tools:
+
+```bash
+npx @openziti/ziti-mcp-server init --tools 'list*,get*'
+```
+
+**Windsurf**
+
+```bash
+npx @openziti/ziti-mcp-server init --client windsurf
+```
+
+**Cursor**
+
+Step 1:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=ziti&config=eyJjb21tYW5kIjoibnB4IC15IEBhdXRoMC9hdXRoMC1tY3Atc2VydmVyIHJ1biIsImNhcGFiaWxpdGllcyI6WyJ0b29scyJdLCJlbnYiOnsiREVCVUciOiJhdXRoMC1tY3AifX0%3D)
+
+Step 2:
+
+```bash
+npx @openziti/ziti-mcp-server init --client cursor
+```
+
+**Cursor with limited tools access**
+
+```bash
+npx @openziti/ziti-mcp-server init --client cursor --tools 'listIdentities,listIdentity'
+```
+
+**VS Code**
+
+```bash
+npx @openziti/ziti-mcp-server init --client vscode
+```
+
+You can configure VS Code for either global or workspace scope:
+
+- **Global**: Available in all VS Code instances
+- **Workspace**: Available only in a specific project/repository
+
+The command will prompt you to choose your preferred scope and automatically configure the appropriate `mcp.json` file.
+
+**VS Code with limited tools access**
+
+```bash
+npx @openziti/ziti-mcp-server init --client vscode --tools 'list*,get*' --read-only
+```
+
+**Other MCP Clients**
+
+To use Ziti MCP Server with any other MCP Client, you can manually add this configuration to the client and restart for changes to take effect:
+
+```json
+{
+  "mcpServers": {
+    "ziti": {
+      "command": "npx",
+      "args": ["-y", "@openziti/ziti-mcp-server", "run"],
+      "capabilities": ["tools"],
+      "env": {
+        "DEBUG": "ziti-mcp"
+      }
+    }
+  }
+}
+```
+
+You can add `--tools '<pattern>'` to the args array to control which tools are available. See [Security Best Practices](#-security-best-practices-for-tool-access) for recommended patterns.
+
+### Authorize with IdP
+
+Your browser will automatically open to initiate the OAuth 2.0 device authorization flow. Log into your IdP account and grant the requested permissions.
+
+> [!NOTE]
+> Credentials are securely stored in your system's keychain. You can optionally verify storage through your keychain management tool. Check out [Authentication](#-authentication) for more info.
+
+### Verify your integration
+
+Restart your MCP Client (Claude Desktop, Windsurf, Cursor, Warp, etc.) and ask it to help you manage your Ziti network
+
+## 🕸️ Architecture
+
+The Ziti MCP Server implements the Model Context Protocol, allowing Claude to:
+
+1. Request a list of available Ziti tools
+2. Call specific tools with parameters
+3. Receive structured responses from the Ziti Management API
+
+The server handles authentication, request validation, and secure communication with the Ziti Management API.
+
+<div align="center">
+  <img src="assets/arch.jpg" alt="Ziti MCP Server" width="800">
+</div>
+
+> [!NOTE]
+> The server operates as a local process that connects to Claude Desktop, enabling secure communication without exposing your Ziti credentials.
+
+## 🔐 Authentication
+
+The Ziti MCP Server uses the Ziti Management API and requires authentication to access your Ziti network.
+
+### Initial Setup
+
+> [!NOTE]
+> Users should authenticate with [client credentials](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). 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)
+
+To authenticate the MCP Server:
+
+```bash
+npx @openziti/ziti-mcp-server init --idp-domain <idp-domain> --idp-client-id <idp-client-id> --idp-client-secret <idp-client-secret>
+```
+
+> [!IMPORTANT]
+>
+> The `init` command needs to be run whenever:
+>
+> - You're setting up the MCP Server for the first time
+> - You've logged out from a previous session
+> - You want to switch to a different Ziti network
+> - Your token has expired
+>
+> The `run` command will automatically check for token validity before starting the server and will provide helpful error messages if authentication is needed.
+
+### Session Management
+
+To see information about your current authentication session:
+
+```bash
+npx @openziti/ziti-mcp-server session
+```
+
+### Logging Out
+
+For security best practices, always use the logout command when you're done with a session:
+
+```bash
+npx @openziti/ziti-mcp-server logout
+```
+
+This ensures your authentication tokens are properly removed from the system keychain.
+
+### Authentication Flow
+
+The Ziti MCP server uses OAuth 2.0 device authorization flow for secure authentication with the IdP. Your credentials are stored securely in your system's keychain and are never exposed in plain text.
+
+<div align="center">
+  <img src="assets/auth-seq.jpg" alt="Authentication Sequence Diagram" width="800">
+</div>
+
+## 🛠️ Supported Tools
+
+The Ziti MCP Server provides **126 tools** for managing your Ziti network through natural language. Tools are organized by resource type.
+
+> **Tip:** Use `--read-only` or `--tools` patterns to expose only the tools you need. See [Security Best Practices](#-security-best-practices-for-tool-access).
+
+### Identities
+
+CRUD operations, relationship queries, and lifecycle management for Ziti Identities.
+
+| Tool                                 | Description                                                                 |
+| ------------------------------------ | --------------------------------------------------------------------------- |
+| `listIdentities`                     | List all identities in the Ziti network                                     |
+| `listIdentity`                       | Get details about a specific identity                                       |
+| `createIdentity`                     | Create a new identity (name, admin, authPolicy, externalId, roleAttributes) |
+| `deleteIdentity`                     | Delete an identity                                                          |
+| `updateIdentity`                     | Update an existing identity                                                 |
+| `listIdentityServices`               | List services accessible by an identity                                     |
+| `listIdentityEdgeRouters`            | List edge routers accessible by an identity                                 |
+| `listIdentityServicePolicies`        | List service policies that apply to an identity                             |
+| `listIdentityEdgeRouterPolicies`     | List edge router policies that apply to an identity                         |
+| `listIdentityServiceConfigs`         | List service configs associated with an identity                            |
+| `getIdentityPolicyAdvice`            | Check whether an identity can dial/bind a service and get policy advice     |
+| `listIdentityRoleAttributes`         | List all role attributes in use by identities                               |
+| `disableIdentity`                    | Temporarily disable an identity for a specified duration                    |
+| `enableIdentity`                     | Re-enable a previously disabled identity                                    |
+| `getIdentityAuthenticators`          | List authenticators for an identity                                         |
+| `getIdentityEnrollments`             | List enrollments for an identity                                            |
+| `getIdentityFailedServiceRequests`   | List failed service requests for an identity                                |
+| `getIdentityPostureData`             | Get posture data for an identity                                            |
+| `removeIdentityMfa`                  | Remove MFA from an identity                                                 |
+| `updateIdentityTracing`              | Update tracing configuration for an identity                                |
+| `associateIdentityServiceConfigs`    | Associate service/config pairs with an identity                             |
+| `disassociateIdentityServiceConfigs` | Remove service/config associations from an identity                         |
+
+**Example prompts:**
+
+- `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`
+- `Disable identity abc123 for 60 minutes`
+- `What posture data does identity xyz have?`
+
+### Services
+
+CRUD operations and relationship queries for Ziti Services.
+
+| Tool                                   | Description                                                                                                     |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `listServices`                         | List all services in the Ziti network                                                                           |
+| `listService`                          | Get details about a specific service                                                                            |
+| `createService`                        | Create a new service (name, encryptionRequired, configs, roleAttributes, terminatorStrategy, maxIdleTimeMillis) |
+| `deleteService`                        | Delete a service                                                                                                |
+| `updateService`                        | Update an existing service                                                                                      |
+| `listServiceIdentities`                | List identities that have access to a service                                                                   |
+| `listServiceEdgeRouters`               | List edge routers accessible by a service                                                                       |
+| `listServiceTerminators`               | List terminators for a service                                                                                  |
+| `listServiceConfig`                    | List configs associated with a service                                                                          |
+| `listServiceServicePolicies`           | List service policies that apply to a service                                                                   |
+| `listServiceServiceEdgeRouterPolicies` | List service edge router policies that apply to a service                                                       |
+| `listServiceRoleAttributes`            | List all role attributes in use by services                                                                     |
+
+**Example prompts:**
+
+- `Show me all Ziti services`
+- `Which identities can access the 'webapp' service?`
+- `Create a new service called 'my-api' with encryption required`
+
+### Edge Routers
+
+CRUD operations, relationship queries, and re-enrollment for Ziti Edge Routers.
+
+| Tool                                      | Description                                                                                     |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `listEdgeRouters`                         | List all edge routers in the Ziti network                                                       |
+| `listEdgeRouter`                          | Get details about a specific edge router                                                        |
+| `createEdgeRouter`                        | Create a new edge router (name, isTunnelerEnabled, roleAttributes, cost, noTraversal, disabled) |
+| `deleteEdgeRouter`                        | Delete an edge router                                                                           |
+| `updateEdgeRouter`                        | Update an existing edge router                                                                  |
+| `listEdgeRouterIdentities`                | List identities accessible by an edge router                                                    |
+| `listEdgeRouterServices`                  | List services accessible by an edge router                                                      |
+| `listEdgeRouterEdgeRouterPolicies`        | List edge router policies that apply to an edge router                                          |
+| `listEdgeRouterServiceEdgeRouterPolicies` | List service edge router policies that apply to an edge router                                  |
+| `listEdgeRouterRoleAttributes`            | List all role attributes in use by edge routers                                                 |
+| `reEnrollEdgeRouter`                      | Re-enroll an edge router, generating new certificates                                           |
+
+**Example prompts:**
+
+- `List all edge routers and their status`
+- `Which services are accessible through edge router xyz?`
+- `Re-enroll edge router abc123`
+
+### Edge Router Policies
+
+CRUD operations and relationship queries for Edge Router Policies.
+
+| Tool                              | Description                                                                      |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `listEdgeRouterPolicies`          | List all edge router policies                                                    |
+| `listEdgeRouterPolicy`            | Get details about a specific edge router policy                                  |
+| `createEdgeRouterPolicy`          | Create a new edge router policy (name, semantic, edgeRouterRoles, identityRoles) |
+| `deleteEdgeRouterPolicy`          | Delete an edge router policy                                                     |
+| `updateEdgeRouterPolicy`          | Update an existing edge router policy                                            |
+| `listEdgeRouterPolicyEdgeRouters` | List edge routers associated with a policy                                       |
+| `listEdgeRouterPolicyIdentities`  | List identities associated with a policy                                         |
+
+**Example prompts:**
+
+- `List all edge router policies`
+- `Which identities are covered by edge router policy xyz?`
+- `Create an edge router policy that gives all identities access to all edge routers`
+
+### Service Edge Router Policies
+
+CRUD operations and relationship queries for Service Edge Router Policies.
+
+| Tool                                     | Description                                                                             |
+| ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| `listServiceEdgeRouterPolicies`          | List all service edge router policies                                                   |
+| `listServiceEdgeRouterPolicy`            | Get details about a specific service edge router policy                                 |
+| `createServiceEdgeRouterPolicy`          | Create a new service edge router policy (name, semantic, edgeRouterRoles, serviceRoles) |
+| `deleteServiceEdgeRouterPolicy`          | Delete a service edge router policy                                                     |
+| `updateServiceEdgeRouterPolicy`          | Update an existing service edge router policy                                           |
+| `listServiceEdgeRouterPolicyEdgeRouters` | List edge routers associated with a policy                                              |
+| `listServiceEdgeRouterPolicyServices`    | List services associated with a policy                                                  |
+
+**Example prompts:**
+
+- `Show me all service edge router policies`
+- `Which edge routers are in the 'public-access' service edge router policy?`
+- `Create a service edge router policy linking all services to all edge routers`
+
+### Service Policies
+
+CRUD operations and relationship queries for Service Policies (Dial/Bind).
+
+| Tool                             | Description                                                                                                  |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `listServicePolicies`            | List all service policies                                                                                    |
+| `listServicePolicy`              | Get details about a specific service policy                                                                  |
+| `createServicePolicy`            | Create a new service policy (name, type Dial/Bind, semantic, identityRoles, serviceRoles, postureCheckRoles) |
+| `deleteServicePolicy`            | Delete a service policy                                                                                      |
+| `updateServicePolicy`            | Update an existing service policy                                                                            |
+| `listServicePolicyIdentities`    | List identities associated with a policy                                                                     |
+| `listServicePolicyServices`      | List services associated with a policy                                                                       |
+| `listServicePolicyPostureChecks` | List posture checks associated with a policy                                                                 |
+
+**Example prompts:**
+
+- `Show me all Dial service policies`
+- `Which identities are in the 'web-access' service policy?`
+- `Create a Bind policy for the 'my-api' service`
+
+### Configs
+
+CRUD operations and relationship queries for Ziti Configs.
+
+| Tool                 | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| `listConfigs`        | List all configs                               |
+| `listConfig`         | Get details about a specific config            |
+| `createConfig`       | Create a new config (name, configTypeId, data) |
+| `deleteConfig`       | Delete a config                                |
+| `updateConfig`       | Update an existing config                      |
+| `listConfigServices` | List services that use a specific config       |
+
+**Example prompts:**
+
+- `List all configs in the network`
+- `Which services use config abc123?`
+- `Create a new intercept.v1 config for my-service`
+
+### Config Types
+
+CRUD operations for Ziti Config Types.
+
+| Tool                       | Description                                      |
+| -------------------------- | ------------------------------------------------ |
+| `listConfigTypes`          | List all config types                            |
+| `listConfigType`           | Get details about a specific config type         |
+| `createConfigType`         | Create a new config type (name, schema)          |
+| `deleteConfigType`         | Delete a config type                             |
+| `updateConfigType`         | Update an existing config type                   |
+| `listConfigsForConfigType` | List all configs that use a specific config type |
+
+**Example prompts:**
+
+- `What config types are available?`
+- `Show me all configs using the intercept.v1 config type`
+- `Create a new config type with a custom JSON schema`
+
+### Auth Policies
+
+CRUD operations for Auth Policies (primary cert/extJwt/updb and secondary requirements).
+
+| Tool               | Description                                                                               |
+| ------------------ | ----------------------------------------------------------------------------------------- |
+| `listAuthPolicies` | List all auth policies                                                                    |
+| `listAuthPolicy`   | Get details about a specific auth policy                                                  |
+| `createAuthPolicy` | Create a new auth policy (primary cert, extJwt, updb settings; secondary MFA requirement) |
+| `deleteAuthPolicy` | Delete an auth policy                                                                     |
+| `updateAuthPolicy` | Update an existing auth policy                                                            |
+
+**Example prompts:**
+
+- `List all auth policies`
+- `Show me the details of the default auth policy`
+- `Create an auth policy that requires MFA as a secondary factor`
+
+### Authenticators
+
+CRUD operations for Authenticators (updb/cert).
+
+| Tool                  | Description                                                                  |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `listAuthenticators`  | List all authenticators                                                      |
+| `listAuthenticator`   | Get details about a specific authenticator                                   |
+| `createAuthenticator` | Create a new authenticator (method, identityId, username, password, certPem) |
+| `deleteAuthenticator` | Delete an authenticator                                                      |
+| `updateAuthenticator` | Update an existing authenticator                                             |
+
+**Example prompts:**
+
+- `List all authenticators in the network`
+- `Show me the authenticators for identity xyz`
+- `Create a new updb authenticator for identity abc123`
+
+### Certificate Authorities
+
+CRUD operations, JWT retrieval, and verification for Certificate Authorities.
+
+| Tool       | Description                                                                        |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `listCas`  | List all certificate authorities                                                   |
+| `listCa`   | Get details about a specific CA                                                    |
+| `createCa` | Create a new CA (name, certPem, isAuthEnabled, enrollment settings, identityRoles) |
+| `deleteCa` | Delete a CA                                                                        |
+| `updateCa` | Update an existing CA                                                              |
+| `getCaJwt` | Get the JWT for a CA (used for enrollment)                                         |
+| `verifyCa` | Verify a CA with a signed PEM certificate                                          |
+
+**Example prompts:**
+
+- `List all certificate authorities`
+- `Get the JWT for CA abc123`
+- `Verify CA xyz with this PEM certificate`
+
+### External JWT Signers
+
+CRUD operations for External JWT Signers.
+
+| Tool                      | Description                                                                            |
+| ------------------------- | -------------------------------------------------------------------------------------- |
+| `listExternalJwtSigners`  | List all external JWT signers                                                          |
+| `listExternalJwtSigner`   | Get details about a specific external JWT signer                                       |
+| `createExternalJwtSigner` | Create a new external JWT signer (name, issuer, audience, certPem, jwksEndpoint, etc.) |
+| `deleteExternalJwtSigner` | Delete an external JWT signer                                                          |
+| `updateExternalJwtSigner` | Update an existing external JWT signer                                                 |
+
+**Example prompts:**
+
+- `List all external JWT signers`
+- `Show me the details of the Demo JWT signer`
+- `Create a new external JWT signer for my IdP`
+
+### Posture Checks
+
+CRUD operations, type queries, and role attributes for Posture Checks.
+
+| Tool                             | Description                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| `listPostureChecks`              | List all posture checks                                                            |
+| `listPostureCheck`               | Get details about a specific posture check                                         |
+| `createPostureCheck`             | Create a new posture check (name, typeId: OS/PROCESS/DOMAIN/MAC/MFA/PROCESS_MULTI) |
+| `deletePostureCheck`             | Delete a posture check                                                             |
+| `updatePostureCheck`             | Update an existing posture check                                                   |
+| `listPostureCheckRoleAttributes` | List all role attributes in use by posture checks                                  |
+| `listPostureCheckTypes`          | List all available posture check types                                             |
+| `detailPostureCheckType`         | Get details about a specific posture check type                                    |
+
+**Example prompts:**
+
+- `List all posture checks`
+- `What posture check types are available?`
+- `Create a new MFA posture check called 'require-mfa'`
+
+### Routers
+
+CRUD operations for fabric Routers.
+
+| Tool           | Description                                             |
+| -------------- | ------------------------------------------------------- |
+| `listRouters`  | List all routers                                        |
+| `listRouter`   | Get details about a specific router                     |
+| `createRouter` | Create a new router (name, cost, noTraversal, disabled) |
+| `deleteRouter` | Delete a router                                         |
+| `updateRouter` | Update an existing router                               |
+
+**Example prompts:**
+
+- `List all routers in the network`
+- `Show me details for router xyz`
+- `Create a new router with cost 100`
+
+### Transit Routers
+
+CRUD operations for Transit Routers.
+
+| Tool                  | Description                                 |
+| --------------------- | ------------------------------------------- |
+| `listTransitRouters`  | List all transit routers                    |
+| `listTransitRouter`   | Get details about a specific transit router |
+| `createTransitRouter` | Create a new transit router                 |
+| `deleteTransitRouter` | Delete a transit router                     |
+| `updateTransitRouter` | Update an existing transit router           |
+
+**Example prompts:**
+
+- `List all transit routers`
+- `Show me the details of transit router abc123`
+
+### Terminators
+
+CRUD operations for Terminators.
+
+| Tool               | Description                                                                   |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `listTerminators`  | List all terminators                                                          |
+| `listTerminator`   | Get details about a specific terminator                                       |
+| `createTerminator` | Create a new terminator (service, router, binding, address, cost, precedence) |
+| `deleteTerminator` | Delete a terminator                                                           |
+| `updateTerminator` | Update an existing terminator                                                 |
+
+**Example prompts:**
+
+- `List all terminators`
+- `Show me terminators for the 'my-service' service`
+- `Create a terminator binding my-service to router xyz`
+
+### Enrollments
+
+CRUD operations and refresh for Enrollments.
+
+| Tool                | Description                                                             |
+| ------------------- | ----------------------------------------------------------------------- |
+| `listEnrollments`   | List all enrollments                                                    |
+| `listEnrollment`    | Get details about a specific enrollment                                 |
+| `createEnrollment`  | Create a new enrollment (identityId, method: ott/ottca/updb, expiresAt) |
+| `deleteEnrollment`  | Delete an enrollment                                                    |
+| `refreshEnrollment` | Refresh an expired enrollment with a new expiration time                |
+
+**Example prompts:**
+
+- `List all pending enrollments`
+- `Create a new OTT enrollment for identity abc123`
+- `Refresh the expired enrollment xyz with a new expiration date`
+
+### Controller Settings
+
+CRUD operations for Controller Settings (OIDC configuration).
+
+| Tool                               | Description                                              |
+| ---------------------------------- | -------------------------------------------------------- |
+| `listControllerSettings`           | List all controller settings                             |
+| `listControllerSetting`            | Get details about a specific controller setting          |
+| `createControllerSetting`          | Create a new controller setting                          |
+| `deleteControllerSetting`          | Delete a controller setting                              |
+| `updateControllerSetting`          | Update an existing controller setting                    |
+| `detailControllerSettingEffective` | Get the effective (merged) value of a controller setting |
+
+**Example prompts:**
+
+- `List all controller settings`
+- `Show me the effective value of controller setting xyz`
+- `Update the OIDC redirect URIs for the controller`
+
+### Controllers & System Info
+
+| Tool                         | Description                                       |
+| ---------------------------- | ------------------------------------------------- |
+| `listControllers`            | List all controllers in the Ziti network          |
+| `listRoot`                   | Get controller version and root information       |
+| `listEnumeratedCapabilities` | List all capabilities supported by the controller |
+| `listSummary`                | Get a summary of entity counts across the network |
+
+**Example prompts:**
+
+- `What version is the Ziti controller running?`
+- `Give me a summary of the network — how many identities, services, and routers exist?`
+- `What capabilities does this controller support?`
+
+### Identity Types
+
+| Tool                 | Description                                |
+| -------------------- | ------------------------------------------ |
+| `listIdentityTypes`  | List all identity types available          |
+| `detailIdentityType` | Get details about a specific identity type |
+
+**Example prompts:**
+
+- `What identity types are available?`
+- `Show me the details of the 'User' identity type`
+
+### Sessions
+
+| Tool            | Description                          |
+| --------------- | ------------------------------------ |
+| `listSessions`  | List all sessions                    |
+| `listSession`   | Get details about a specific session |
+| `deleteSession` | Delete a session                     |
+
+**Example prompts:**
+
+- `List all active sessions`
+- `Show me details for session xyz`
+- `Delete session abc123`
+
+### API Sessions
+
+| Tool               | Description                              |
+| ------------------ | ---------------------------------------- |
+| `listApiSessions`  | List all API sessions                    |
+| `listApiSession`   | Get details about a specific API session |
+| `deleteApiSession` | Delete an API session                    |
+
+**Example prompts:**
+
+- `List all API sessions`
+- `Show me details for API session xyz`
+- `Delete API session abc123`
+
+### 🔒 Security Best Practices for Tool Access
+
+When configuring the Ziti MCP Server, it's important to follow security best practices by limiting tool access based on your specific needs. The server provides flexible configuration options that let you control which tools AI assistants can access.
+
+You can easily restrict tool access using the `--tools` and `--read-only` flags when starting the server:
+
+```bash
+# Enable only read-only operations
+npx @openziti/ziti-mcp-server run --read-only
+
+# Alternative way to enable only read-only operations
+npx @openziti/ziti-mcp-server run --tools 'list*,get*'
+
+# Limit to just identity-related tools
+npx @openziti/ziti-mcp-server run --tools '*Identit*'
+
+# Limit to read-only identity-related tools
+# Note: --read-only takes priority when used with --tools
+npx @openziti/ziti-mcp-server run --tools '*Identit*' --read-only
+
+# Run the server with all tools enabled
+npx @openziti/ziti-mcp-server run --tools '*'
+```
+
+> [!IMPORTANT]
+> When both `--read-only` and `--tools` flags are used together, the `--read-only` flag takes priority for security. This means even if your `--tools` pattern matches non-read-only tools, only read-only operations will be available. This ensures you can rely on the `--read-only` flag as a security guardrail.
+
+This approach offers several important benefits:
+
+1. **Enhanced Security**: By limiting available tools to only what's needed, you reduce the potential attack surface and prevent unintended modifications to your Ziti network.
+
+2. **Better Performance**: Providing fewer tools to AI assistants actually improves performance. When models have access to many tools, they use more of their context window to reason about which tools to use. With a focused set of tools, you'll get faster and more relevant responses.
+
+3. **Resource-Based Access Control**: You can configure different instances of the MCP server with different tool sets based on specific needs - development environments might need full access, while production environments could be limited to read operations only.
+
+4. **Simplified Auditing**: With limited tools, it's easier to track which operations were performed through the AI assistant.
+
+For most use cases, start with the minimum set of tools needed and add more only when required. This follows the principle of least privilege - a fundamental security best practice.
+
+### 🧪 Security Scanning
+
+We recommend regularly scanning this server, and any other MCP-compatible servers you deploy, with community tools built to surface protocol-level risks and misconfigurations.
+
+These scanners help identify issues across key vulnerability classes including: server implementation bugs, tool definition and lifecycle risks, interaction and data flow weaknesses, and configuration or environment gaps.
+
+Useful tools include:
+
+- **[mcpscan.ai](https://mcpscan.ai)**  
+  Web-based scanner that inspects live MCP endpoints for exposed tools, schema enforcement gaps, and other issues.
+
+- **[mcp-scan](https://github.com/invariantlabs-ai/mcp-scan)**  
+  CLI tool that simulates attack paths and evaluates server behavior from a client perspective.
+
+These tools are not a substitute for a full audit, but they offer meaningful guardrails and early warnings. We suggest including them in your regular security review process.
+
+## 🩺 Troubleshooting
+
+When encountering issues with the Ziti MCP Server, several troubleshooting options are available to help diagnose and resolve problems.
+
+Start troubleshooting by exploring all available commands and options:
+
+```bash
+npx @openziti/ziti-mcp-server help
+```
+
+### 🚥 Operation Modes
+
+#### 🐞 Debug Mode
+
+- More detailed logging
+- Enable by setting environment variable: `export DEBUG=ziti-mcp`
+
+> [!TIP]
+> Debug mode is particularly useful when troubleshooting connection or authentication issues.
+
+#### 🔑 Scope Selection
+
+The server provides an interactive scope selection interface during initialization:
+
+- **Interactive Selection**: Navigate with arrow keys and toggle selections with spacebar
+- **No Default Scopes**: By default, no scopes are selected for maximum security
+- **Glob Pattern Support**: Quickly select multiple related scopes with patterns:
+
+  ```bash
+  # Select all read scopes
+  npx @openziti/ziti-mcp-server init --scopes 'read:*'
+
+  # Select multiple scope patterns (comma-separated)
+  npx @openziti/ziti-mcp-server init --scopes 'read:*,create:identities,update:services'
+  ```
+
+> [!NOTE]
+> Selected scopes determine what operations the MCP server can perform on your Ziti network.
+
+### ⚙️ Configuration
+
+#### Other MCP Clients:
+
+To use Ziti MCP Server with any other MCP Client, you can add this configuration to the client and restart for changes to take effect:
+
+```json
+{
+  "mcpServers": {
+    "ziti": {
+      "command": "npx",
+      "args": ["-y", "@openziti/ziti-mcp-server", "run"],
+      "capabilities": ["tools"],
+      "env": {
+        "DEBUG": "ziti-mcp"
+      }
+    }
+  }
+}
+```
+
+> [!NOTE]  
+> You can manually update if needed or if any unexpected errors occur during the npx init command.
+
+### 🚨 Common Issues
+
+1. **Authentication Failures**
+   - Ensure you have the correct permissions in your IdP tenant and Ziti network
+   - Try re-initializing with `npx @openziti/ziti-mcp-server init`
+
+2. **Claude Desktop Can't Connect to the Server**
+   - Restart Claude Desktop after installation
+   - Check that the server is running with `ps aux | grep ziti-mcp`
+
+3. **API Errors or Permission Issues**
+   - Enable debug mode with `export DEBUG=ziti-mcp`
+   - Check your token status: `npx @openziti/ziti-mcp-server session`
+   - Reinitialize with specific scopes: `npx @openziti/ziti-mcp-server init --scopes 'read:*,update:*,create:*'`
+   - If a specific operation fails, you may be missing the required scope
+
+4. **Invalid Configuration Error**
+   - This typically happens when your authorization token is missing or expired
+   - Run `npx @openziti/ziti-mcp-server session` to check your token status
+   - If expired or missing, run `npx @openziti/ziti-mcp-server init` to authenticate
+
+> [!TIP]
+> Most connection issues can be resolved by restarting both the server and Claude Desktop.
+
+## 📋 Debug logs
+
+Enable debug mode to view detailed logs:
+
+```sh
+export DEBUG=ziti-mcp
+```
+
+Get detailed MCP Client logs from Claude Desktop:
+
+```sh
+# Follow logs in real-time
+tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
+```
+
+For advanced troubleshooting, use the MCP Inspector:
+
+```sh
+npx @modelcontextprotocol/inspector -e DEBUG='ziti-mcp' @openziti/ziti-mcp-server run
+```
+
+For detailed MCP Server logs, run the server in debug mode:
+
+```bash
+DEBUG=ziti-mcp npx @openziti/ziti-mcp-server run
+```
+
+## 👨‍💻 Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/openziti/ziti-mcp-server.git
+cd ziti-mcp-server
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Initiate device auth flow
+npx . init
+
+# Configure your MCP Client (e.g. Claude Desktop) with MCP server path
+npm run setup
+```
+
+### Development Scripts
+
+```bash
+# Run directly with TypeScript (no build needed)
+npm run dev
+
+# Run with debug logs enabled
+npm run dev:debug
+
+# Run with MCP inspector for debugging
+npm run dev:inspect
+
+# Run the compiled JavaScript version
+npm run start
+```
+
+> [!NOTE]
+> This server requires [Node.js v18 or higher](https://nodejs.org/en/download).
+
+## 🔒 Security
+
+The Ziti MCP Server prioritizes security:
+
+- Credentials are stored in the system's secure keychain
+- No sensitive information is stored in plain text
+- Authentication uses OAuth 2.0 device authorization flow
+- No permissions (scopes) are requested by default
+- Interactive scope selection allows you to choose exactly which permissions to grant
+- Support for glob patterns to quickly select related scopes (e.g., `read:*`)
+- Easy token removal via `logout` command when no longer needed
+
+> [!IMPORTANT]
+> For security best practices, always use `npx @openziti/ziti-mcp-server logout` when you're done with a session or switching between tenants. This ensures your authentication tokens are properly removed from the system keychain.
+
+> [!CAUTION]
+> Always review the permissions requested during the authentication process to ensure they align with your security requirements.
+
+### Reporting Issues
+
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/openziti/ziti-mcp-server/issues).