Deploy and use the Portnox MCP Server

The Portnox MCP Server acts as a secure translation layer between AI assistants and the Portnox Cloud REST API. Rather than letting an AI model call the API directly, the server exposes a fixed set of MCP tools that map to supported Portnox operations. When an AI assistant makes a request, it calls the matching MCP tool, which authenticates to Portnox Cloud, performs the operation, and returns structured results to the AI. It is available in the public Docker repository as portnox/portnox-mcp. It has no virtual machine equivalent.

Depending on the permissions of the Portnox administrator account or token used, the server can perform both read-only operations, such as searching for devices or retrieving configuration, and administrative operations, such as updating sites, modifying network devices, or blocking and deleting endpoints. Currently supported resources are:

• Network Access Servers (NAS): list switches and network devices, and batch update NAS configuration.

• Sites: create, update, retrieve, and delete sites, and modify site subnet and IP range rules.

• Endpoints and devices: search for managed devices, view device information, block or unblock devices, and delete devices.

The server is intended for network, security, and NAC administrators, IT operations and SOC teams, and developers building AI-driven operational workflows around Portnox Cloud, since it removes the need to build a custom integration against the REST API directly. Typical requests an AI assistant can handle through the server include finding all devices blocked today, listing switches at a specific site, blocking a specific endpoint, identifying which site contains a given subnet, updating a site’s IP ranges, or listing unmanaged endpoints that authenticated within a given period.

• You need an MCP-compatible AI client to connect to the server, such as Claude Desktop, Claude Code, GitHub Copilot, Visual Studio Code, ChatGPT, or Gemini.

• You can run the container on Linux, or on Windows or macOS via Docker Desktop. If running in a VM environment, we recommend Linux for the best results, since Windows and macOS would require double virtualization.

• You should use a dedicated administrator account scoped to only the permissions your intended workflows need, following the principle of least privilege, rather than a broad or personal admin account, since the server can perform administrative actions.

• You must authenticate with Portnox Cloud using either a Portnox API token (recommended, provided through PORTNOX_TOKEN_FILE or PORTNOX_TOKEN), or a local Portnox administrator username and password (PORTNOX_USERNAME and PORTNOX_PASSWORD). Federated identity providers such as Microsoft Entra ID, Okta, Google Workspace, or Active Directory are not supported for this purpose.

• You can enable HTTPS using either your own certificate and key files, a PKCS#12 (PFX) bundle, or nothing at all, since the server can generate a self-signed certificate automatically.

• Follow the firewall rules in the following topic: How to set up the firewall for Portnox Docker containers to connect to Portnox Cloud.

The container accepts configuration either as environment variables, or as equivalent command-line arguments appended after the image name.

Environment variables:

The same options are also available as command-line arguments, appended after the image name:

Example, using credential-based authentication:

sudo docker run --rm -p 8765:8765 \
  -e MCP_ENABLE_HTTPS='true' \
  -e PORTNOX_USERNAME='kosh@vorlon.com' \
  -e PORTNOX_PASSWORD='password' \
  portnox/portnox-mcp:latest \
  python /app/server.py --transport streamable-http --host 0.0.0.0 --port 8765

Example, using token-based authentication:

sudo docker run --rm -p 8765:8765 \
  -e MCP_ENABLE_HTTPS='true' \
  -e PORTNOX_TOKEN='your_api_token' \
  portnox/portnox-mcp:latest \
  python /app/server.py --transport streamable-http --host 0.0.0.0 --port 8765

For a Claude Desktop-specific walkthrough, including generating a token and configuring the client, see below. For other AI clients, the MCP client configuration follows the same general pattern. If your client connects over a self-signed certificate, disable certificate validation on the client side:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp_server_ip:mcp_server_port/mcp"],
      "env": {"NODE_TLS_REJECT_UNAUTHORIZED": "0"}
    }
  }
}

If you are running the server over plain HTTP instead of HTTPS, use the following client configuration instead:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "mcp_server_ip:mcp_server_port/mcp", "--allow-http", "--transport", "http-first"]
    }
  }
}

• Set PORTNOX_VERIFY_TLS to false only when troubleshooting a TLS problem against Portnox Cloud. Do not use this in production.

• Use --log-level DEBUG for more detailed log output, and --log-file to write logs to a file instead of standard output.

• Adjust PORTNOX_TIMEOUT_SECONDS if requests to Portnox Cloud are timing out under normal conditions.