Deploy and use the Portnox MCP Server

In this topic, you will learn how to deploy the Portnox MCP Server, configure authentication, connect an MCP-compatible AI client such as Claude Desktop, and verify the connection to Portnox Cloud.

Important:

For the latest deployment options, TLS settings, and AI client examples, see Docker Hub.

Important:

The Portnox MCP Server is a community-supported utility created to complement Portnox Cloud. It is not an official Portnox Cloud product or feature. It is provided free of charge under the Apache License 2.0, and may be used and modified in accordance with that license. Support is available only through the project’s GitHub repository. It is provided as is and is not covered by Portnox technical support, SLAs, maintenance commitments, or warranties.

The Portnox MCP Server is a Docker container that exposes the Portnox Cloud REST API through the Model Context Protocol (MCP). AI clients connect to the MCP server, which authenticates with Portnox Cloud, performs API operations, and returns structured results to the AI client.

The server supports the following authentication methods:

Portnox API token (recommended).
Local Portnox administrator username and password.

Note:

In this example guide, we will use Claude Desktop. Adjust your configuration to the requirements of your specific AI client.

Before you begin, make sure you have:

A physical or virtual machine that can run Docker containers.
Docker installed and running (see Portnox Tech Shorts for Linux/macOS and Windows).
A Portnox API token or valid local Portnox administrator credentials.
Claude Desktop installed on the same computer where you will configure the MCP client.
Node.js and npm. The Claude Desktop MCP configuration uses npx to launch the mcp-remote package, which requires Node.js and npm.
npx available in the system PATH. Verify that the node, npm, and npx commands are available before configuring Claude Desktop.

Generate a Portnox Cloud API token.

Settings > Profile Settings > CLOUD API TOKENS as described here.

Note:
Alternatively, you can use your Portnox admin credentials. Federated identity providers such as Microsoft Entra ID, Okta, and Google Workspace are not supported for this purpose.

Start the Portnox MCP Server container.

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

Configure Claude Desktop to connect to the running MCP server.

Locate the Claude Desktop configuration file: Settings > Developer > Edit Config
Open the located configuration JSON file in a text editor of your choice.

Add the Portnox MCP Server configuration to the existing Claude Desktop configuration file.

Do not replace the entire contents of the configuration file. Add the portnox server entry inside the existing mcpServers object. If the file already contains other MCP servers, keep those entries unchanged and add the Portnox MCP Server entry alongside them.

If the configuration file does not contain an mcpServers object, create one using the following structure.

Replace mcp_server_ip with the IP address of the Docker host.

Note:

If Claude Desktop is running on the same computer as Docker, use localhost.

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

Example:

{
  "preferences": {
    "launchPreviewPersistedWorkspaces": [],
    "launchPreviewSessionScopedSessions": [],
    "coworkHipaaRestricted": false,
    "coworkWebSearchEnabled": true,
    "remoteToolsDeviceName": "portnox",
    "coworkModelAutoFallbackByAccount": {
      "12345678-1234-5678-9abc-1234567890ab": true
    },
    "coworkScheduledTasksEnabled": false,
    "ccdScheduledTasksEnabled": false,
    "epitaxyPrefs": {
      "ccd-sessions-filter": {
        "state": {
          "selectedProjects": []
        },
        "version": 0
      }
    },
    "bypassPermissionsGateByAccount": {
      "12345678-1234-5678-9abc-1234567890ab": false
    }
  },
  "coworkUserFilesPath": "C:\\Users\\Kosh\\Claude",
  "mcpServers": {
    "portnox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://localhost:8765/mcp"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Save the file and restart Claude Desktop.

Verify that Claude Desktop detects the Portnox MCP server.

After restarting Claude Desktop, open a new chat. You should see a tool indicator showing that the portnox MCP server is available.

If the tool indicator does not appear, check the Docker terminal for startup errors and confirm that the JSON configuration file is valid. Also check that you have Node.js and npc installed.
Test the connection by running a query from Claude Desktop.
Type the following prompt into the Claude Desktop chat window:
```
List all unmanaged endpoints that authenticated this week.
```
When Claude asks for permission to use the portnox tool, approve the request.

A successful response returns data from your Portnox Cloud tenant, such as endpoint names, MAC addresses, authentication timestamps, or site information.