Deploy and use the Portnox MCP Server

In this topic, you will learn how to deploy the Portnox MCP Server and connect an MCP-compatible AI client such as Claude Desktop. You will also find answers to frequently asked questions.

Deploy the Portnox MCP Server with Claude Desktop

In this topic, you will learn how to deploy the Portnox MCP Server, configure authentication, connect Claude Desktop as an MCP-compatible AI client, 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.
  1. 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.
  2. 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
  3. Configure Claude Desktop to connect to the running MCP server.
    1. Locate the Claude Desktop configuration file: Settings > Developer > Edit Config
    2. Open the located configuration JSON file in a text editor of your choice.
    3. 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"
      }
    }
  }
}
    4. Save the file and restart Claude Desktop.
  4. 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 npm installed.

  5. 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.

Portnox MCP Server FAQ

In this topic, you will find answers to frequently asked questions about the Portnox MCP Server.

Is the Portnox MCP Server officially supported?

No. You cannot contact Portnox technical support for assistance deploying or configuring the Portnox MCP Server. Support is provided only through the project’s GitHub repository.

The Portnox MCP Server is a community-supported utility created to complement Portnox Cloud, and 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. It is provided as is and is not covered by Portnox technical support, SLAs, maintenance commitments, or warranties.

How do I request a feature or report an issue with the Portnox MCP Server?

You can post feature requests or bug reports directly on the project’s GitHub repository, or use the Portnox Cloud feedback form for feature requests.

Can I use my Entra ID, Okta, or other federated credentials with the Portnox MCP Server?
No. The Portnox API does not support federated credentials from external identity providers such as Entra ID. You must use a Portnox API token with a federated account instead. However, we recommend that you create a separate local Portnox Cloud administrator account for MCP Server use.
What permissions does the Portnox MCP Server need?
The MCP Server operates in the context of whichever account or token you provide. For example, if the account is a read-only administrator, the MCP Server is limited to read-only operations, and cannot make any changes.
Do actions performed through the Portnox MCP Server appear in the Portnox Cloud activity log?
Not yet. Adding MCP Server actions to the activity log is on the roadmap, but is not yet implemented.
Is the Portnox MCP Server tied to a specific Portnox Cloud license or subscription tier?
No. The Portnox MCP Server is available to any Portnox Cloud customer, regardless of license tier, since it works through the same public REST API available to all customers.
Does my AI client limit how many MCP servers I can connect at once?
This depends on your AI client and its pricing tier, not on Portnox. For example, some AI clients only allow configuring a single MCP server on their free tier, while paid tiers may allow multiple servers, or may require a paid subscription to use any MCP server at all. Check your AI client’s current documentation, since these limits are set by the AI vendor and may change over time.
Which AI clients can I use with the Portnox MCP Server?
Besides Claude Desktop, used as the example in the previous topic, the Portnox MCP Server is also compatible with Claude Code, GitHub Copilot, Visual Studio Code, and other MCP-compatible AI clients such as ChatGPT and Gemini. For the current list of compatible clients, see Docker Hub.
What operations can the Portnox MCP Server perform?
In short, the Portnox MCP Server can perform most actions available through the Portnox Cloud REST API, such as querying, creating, and modifying NAS devices, sites, endpoints, and various account types, and executing bulk operations. The set of supported tools is updated frequently as the project develops, so see Docker Hub for the current list of supported operations rather than relying on a fixed list.
Do I have to run the Portnox MCP Server in Docker?
No. Besides the Docker deployment described in the previous topic, the Portnox MCP Server can also run as a Linux daemon without Docker, or as a native Claude Desktop extension with no separate server process running at all. Both alternatives require you to satisfy all software prerequisites yourself. For instructions, see the Portnox Labs MCP Server repository on GitHub.
Is the Docker deployment of the Portnox MCP Server automatically updated?
No. Docker deployments of the Portnox MCP Server are not currently updated by the portnox-autoupdate container. You must pull and redeploy new versions manually.