Skip to main content

Managing CloudConnexa with Plain English: A Developer's Guide to the MCP Server

Abstract

Connect CloudConnexa to Claude Desktop and other MCP-compatible AI clients to inspect networks, users, devices, sessions, DNS records, and access policies using natural language.

If you manage CloudConnexa and you've spent any time in the Administration portal clicking through networks, users, and access policies, you already know the friction. The portal isn't bad; switching contexts is expensive. You're in your IDE, you're in Slack, you're in a terminal, and then you need to answer a question like "which users are currently online?" and suddenly, you're opening a browser, signing in, navigating to the right screen, and you've lost your train of thought.

The CloudConnexa MCP Server changes that. It exposes information about your CloudConnexa environment — including networks, users, devices, access policies, DNS, sessions, and device posture — through a read-only API that an MCP-compatible AI client can call. That means you can ask plain-language questions about your network from inside Claude Desktop, Cursor, VS Code with Cline, or Claude Code, and get real answers pulled directly from your live environment.

This guide walks you through setup and three real-world workflows that show what that actually looks like in practice.

What the CloudConnexa MCP server actually is

Before getting into setup, it helps to understand what's happening under the hood.

MCP (Model Context Protocol) is an open standard that enables AI clients to discover and call external tools consistently. A "server" in MCP terms isn't necessarily a web server. It's a process that exposes a set of capabilities (tools, data, context) that an AI client can invoke. The CloudConnexa MCP server is that process: it wraps the CloudConnexa API and translates your network's state into something an LLM can query.

When you ask Claude, "Which users are online right now?", it doesn't guess; it calls the sessions tool, gets back real session data from your CloudConnexa environment, and summarizes it. The LLM handles the language; the MCP server handles the data retrieval.

The result is that you can manage and inspect your CloudConnexa environment from wherever you're already working, without learning separate query syntax or leaving your tool of choice.

Note

At this time, only read-only tools are available. You can query and inspect your environment extensively, but write operations (such as creating users and modifying policies) aren't yet supported.

Prerequisites

Before getting started, you need to have:

  • A CloudConnexa account with access to the Administration portal.

  • Docker Desktop installed and running.

  • An MCP-compatible client — this guide covers Claude Desktop in detail, but the server also works with Cursor, VS Code with Cline, Claude Code, and 5ire.

  • Git or GitHub CLI if you want to clone the repository instead of downloading the ZIP file.

Step 1: Generate your API credentials

The MCP server authenticates with CloudConnexa using API credentials. You'll need to generate a Client ID and Client Secret from the Administration portal.

  2. Navigate to API & Logs → API.

  3. Select Create Credentials.

  4. Name the credentials (e.g., mcp-server-local).

  5. Select a lifetime. One month or six months is reasonable for local development use.

  6. Set permissions to Read Only (write access isn't supported yet in the current MCP server).

  7. Select Create.

    Important

    Copy your Client ID and Client Secret immediately and store them somewhere secure. The client secret is only shown once.

  8. After saving your credentials, return to the API page.

  9. Turn on the Enable API toggle.

    Note

    Credentials won't work until you enable this. It's easy to miss, so double-check if you run into authentication errors later.

Step 2: Clone and build the MCP server

Clone the repository

  1. Open a terminal (Terminal on macOS/Linux, Command Prompt or PowerShell on Windows).

  2. Navigate to the directory where you want to clone the repository:

    cd /path/to/your/directory

  3. Then choose one of the following methods to download the project:

(Option 1) Git:

  1. Run the clone command to pull the repo to your local machine:

    git clone https://github.com/OpenVPN/cloudconnexa-mcp-server.git

  2. Navigate into the repository directory:

    cd cloudconnexa-mcp-server

(Option 2) GitHub CLI:

  1. Run the clone command to pull the repo to your local machine:

    gh repo clone OpenVPN/cloudconnexa-mcp-server

  2. Navigate into the repository directory.

    cd cloudconnexa-mcp-server

(Option 3) ZIP download:

  1. Open the CloudConnexa MCP Server GitHub repository.

  2. Select the Code button.

  3. Select Download ZIP.

  4. Extract the ZIP file.

  5. In your terminal, navigate to the extracted folder.

Build the Docker image

  • From the repository root, run:

    docker build -t mcp-server-public .

    Note

    The . at the end of the command is required. It tells Docker to use the current directory as the build context.

Start the MCP server

  1. Once the build completes, start the server:

    bash start.sh

  2. When prompted, review and accept the following agreements by entering y to accept or n to decline:

    Agreement

    Notes

    Apache 2.0 License

    Open source license governing the MCP server software.

    OpenVPN Technologies, Inc. Privacy Policy

    Covers how OpenVPN handles your personal data.

    OpenVPN Data Processing Agreement

    Governs data processing terms.

    OpenVPN may log and store your LLM input for monitoring and product improvement purposes

    Review carefully. Any prompts you send through the MCP client may be stored by OpenVPN. Consider this before using the server with sensitive infrastructure data.

    OpenVPN may log and store your Tenant ID, LLM type, and login date

    Mandatory — can't be opted out of.

    OpenVPN Data Retention Policy for MCP Server

    Governs how long logged data is retained.

  3. When prompted, enter your CloudConnexa API Client ID and Client Secret. Refer to Step 1 if you haven't generated these yet.

  4. When prompted for your preferred MCP transport, press Enter to accept the default (sse), or enter streamable-http if your MCP client requires it.

  5. When prompted for a port, press Enter to accept the default (9999), or enter a different port number if 9999 is already in use on your machine.

  6. The server saves your preferences to /root/.openvpn-mcp-server.conf and starts. If you need to update your API credentials, transport, or port later, you can edit this file directly rather than re-running the setup.

  7. The server is now listening on http://127.0.0.1:9999/sse. Leave this terminal running. The server needs to stay active while you're using it.

Step 3: Connect Claude Desktop

Claude Desktop supports MCP servers via a configuration file.

  1. Open Claude Desktop and navigate to Settings → Developer → Edit Config.

    • This opens the claude_desktop_config.json file.

  2. Add the following to the mcpServers section:

    {
      "mcpServers": {
        "openvpnmcp": {
          "url": "http://127.0.0.1:9999/sse",
          "name": "CloudConnexa MCP"
        }
      }
    }

    Tip

    If you already have configuration settings in this file, since Claude Desktop supports multiple MCP servers, we suggest making a backup copy before proceeding.

  3. Save the file and restart Claude Desktop. (Quit and reopen. A window refresh isn't enough.)

  4. After restarting, run a prompt to confirm Claude can see the tools:

    Discover graphql_schema and tell me what tools are available?

  5. This required discovery step lets the MCP client learn about the tools available on the server. Run this discovery prompt before using the CloudConnexa tools.

Three workflows worth knowing

Now for the exciting part: What can you do with this?

Tip

The MCP server exposes tools across helpful categories. When you ask this, it tells you all of the options:

Discover graphql_schema and tell me what tools are available?

Workflow 1: Network and access audit

You're preparing for a security review and need to understand which users have access to which networks, and whether any access policies are broader than they should be.

  • Try these prompts in sequence:

    List all networks and give me a summary of each one.
    For each network, show me which access groups have access to it.
    Are there any users who are members of more than three access groups? List them.
    Show me all device posture policies and which groups they apply to.

What would normally require navigating through multiple Administration portal screens — Networks, Access, Users, Device Posture — becomes a single conversation.

Workflow 2: User and device investigation

A user reports they can't connect, or need to understand what a specific user's environment looks like before a support call.

  • Try these prompts:

    Show me all devices registered to user@example.com.
    When did this user last have an active session?
Show me their last five sessions with start time, end time, and region.
    What device posture policy applies to their devices?
Are their devices currently compliant?
    Which VPN regions are available, and which one are they typically connecting to?

    This kind of triage, usually a sequence of portal lookups across Users, Devices, Sessions, and Posture, can take minutes when you're clicking through a UI. In a conversation, it can take seconds.

Workflow 3: DNS and traffic investigation

Something is behaving unexpectedly on your network, and you want to understand your traffic patterns.

  • Try these prompts:

    Show DNS logs for the past two hours.
Are there any domains being resolved unusually frequently?
    List all custom DNS records configured in the environment.
    What is the default DNS suffix? Is DNS proxying enabled?
    Show me active sessions right now.
How many users are connected and which regions are they using?

The visitedDomains tool accepts a time window, so you can request a specific hour or look back over a longer period. Pair this with session data to correlate traffic patterns with specific users or time ranges.

Combining CloudConnexa with other MCP servers

One of the more interesting possibilities with MCP is that your AI client can use multiple servers in the same conversation. If you have Jira, GitHub, or Slack connected as MCP servers alongside CloudConnexa, you can ask questions that cross system boundaries:

  • Which Jira tickets are open for network access requests, and are those users already in CloudConnexa?
  • Summarize the last week of CloudConnexa session activity and draft a Slack message for the team.

The AI client handles the orchestration. You just ask the question.

Troubleshooting

  • LLM can't find any MCP tools — Run the discovery prompt: Discover graphql_schema. This is required once per session.

  • LLM can't reach MCP tools — Check that the Docker container is still running in your terminal. If it stopped, run bash start.sh again. Also, verify the toggle is green/ON in your MCP client's tool settings.

  • API credentials not working — Double-check that the Enable API toggle is turned on in CloudConnexa under API & Logs → API. Valid credentials still won't authenticate unless you explicitly enable API access.

  • Claude Desktop not seeing the server — Ensure you fully quit and relaunch Claude Desktop after editing the config file. Also, confirm the JSON in your config file is valid. For example, a missing comma or bracket will silently prevent the config from loading.

  • Context window errors — Complex queries across many networks and users can generate large responses. If you hit context limits, try narrowing your questions. For example, ask about a single network or user at a time rather than requesting everything at once.

In this section: