Tutorial: Connect Your AI Agent to Access Server Using the MCP Server⁠

Overview⁠

Use the Access Server MCP server to connect an AI agent such as Claude Code to OpenVPN Access Server through the Web API.

The Model Context Protocol (MCP) is an open standard that lets AI applications connect to external tools and data sources. The Access Server MCP server exposes Access Server information as MCP tools, letting you query your server in natural language rather than manually constructing Web API requests.

The as-mcp-server package currently provides read-only access. You can use it to retrieve server information, users and groups, connection activity, authentication failures, and other operational data, but it doesn't change Access Server configuration.

This tutorial uses Claude Code as the primary MCP client. The server can also work with other MCP-compatible clients such as Claude Desktop, Codex, VS Code, Gemini CLI, Cursor, and OpenCode.

The MCP server runs through uvx. uvx, included with Astral's uv, runs Python command-line tools such as as-mcp-server in an isolated environment, so you don't need to install the package globally.

You can review the source in the OpenVPN/as-mcp-server repository.

Use cases⁠

Audience	Use case
Developers	Explore and test Access Server information through natural-language queries.
IT administrators and DevOps engineers	Check server status, investigate VPN connections, review authentication failures, and retrieve operational information through an AI assistant.
Organizations	Give administrators another read-only interface to retrieve Access Server information and investigate issues.

Where the MCP server runs⁠

This tutorial uses the stdio MCP transport.

With stdio, the MCP client launches as-mcp-server as a local child process and communicates with it through standard input and output. The MCP server therefore runs on the same machine as Claude Code or your other MCP client. It doesn't listen on a separate network port.

A Windows, macOS, or Linux workstation.
An on-premises server.
A cloud VM or other host.

Whichever system you use needs network access to your Access Server.

Prerequisites⁠

Before you begin, ensure you have:

Access Server 3.1.0 or newer.
A dedicated Access Server administrative account that uses local, PAM, RADIUS, or LDAP authentication.
An MCP-compatible client. This tutorial uses Claude Code.
Network access from the MCP client host to the Access Server web services.
Optional but recommended: TOTP MFA enabled for the administrative account.

For TOTP MFA, refer to Tutorial: Turn On TOTP Multi-Factor Authentication. Access Server supports built-in TOTP MFA with local, PAM, LDAP, and RADIUS authentication.

The Access Server Web API is reached through the web services. Ensure the MCP client host can reach TCP 943, or TCP 443 when web service forwarding is enabled.

Install uv, which provides the uvx command used to run as-mcp-server.

Open PowerShell, Command Prompt, or a terminal on the machine where you'll run your MCP client.

Install uv.

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or, with Windows Package Manager:
```
winget install astral-sh.uv
```

macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or, with Homebrew:
```
brew install uv
```

Close and reopen your terminal so the updated PATH takes effect.
Verify the installation:
```
uv --version
```

Configure the Access Server URL and administrative credentials that as-mcp-server uses when calling the Web API.

The setup command stores the connection profile locally. The administrative password is stored through Python's keyring interface, which can use platform credential stores such as Windows Credential Manager, macOS Keychain, or supported Linux keyrings.

Gather the following information:
- Access Server URL beginning with https://, such as https://vpn.example.com.
- Administrative username.
- Administrative password.
- If TOTP MFA is enabled, the current six-digit TOTP MFA code.
Run the interactive setup:
```
uvx as-mcp-server setup
```
Enter the Access Server URL when prompted.
Enter the Admin username.
Enter the Password. The password input is hidden.

If TOTP MFA is enabled, enter the current six-digit TOTP MFA code when prompted.

Example without TOTP MFA:

Access Server URL: https://vpn.example.com
Admin username: mcp-admin
Password (input hidden):
Connected to Access Server 3.2.2 at https://vpn.example.com as mcp-admin

Example with TOTP MFA:

Access Server URL: https://vpn.example.com
Admin username: mcp-admin
Password (input hidden):
MFA code from your authenticator app: 123456
Connected to Access Server 3.2.2 at https://vpn.example.com as mcp-admin

Alternative: Specify the URL and username with flags⁠

You can provide the URL and username in the command and enter only the password interactively:

uvx as-mcp-server setup --url https://vpn.example.com --username mcp-admin

Example output:

Password (input hidden):
Connected to Access Server 3.2.2 at https://vpn.example.com as mcp-admin

To display all setup options:

uvx as-mcp-server setup --help

To clear the saved connection profile:

uvx as-mcp-server setup --clear

Run the command for your operating system.
- Windows PowerShell:
```
claude.cmd mcp add --scope user openvpn-as -- uvx as-mcp-server
```
- macOS or Linux:
```
claude mcp add --scope user openvpn-as -- uvx as-mcp-server
```
Tip
--scope user makes the MCP server available across your Claude Code projects. If you omit --scope user, Claude Code uses local scope by default and registers the server only for the current project.
Confirm that Claude Code reports that it added the server.
- Example output:
```
Added stdio MCP server openvpn-as with command: uvx as-mcp-server to user config
```
- Claude Code registers this as a stdio MCP server. With stdio, Claude Code launches uvx as-mcp-server as a child process and communicates with it over stdin and stdout.

Use the check command to verify that as-mcp-server can authenticate to Access Server.

Run:

uvx as-mcp-server check

Example output:

URL:      https://vpn.example.com (from profile)
User:     mcp-admin (from profile); password from keyring
TLS:      verified
Server:   Access Server 3.2.2 (413ca39f) on Ubuntu 24.04.5 LTS
Keyring:  keyring.backends.Windows.WinVaultKeyring

Confirm that:
- The URL is correct.
- The expected administrative account displays.
- TLS reports verified.
- The Access Server version is detected.
- A supported keyring backend is available.

The exact keyring backend depends on your operating system and local configuration. The Windows example above uses Windows Credential Manager through the Python keyring library.

Confirm that Claude Code can launch the registered MCP server.

Run:
```
claude mcp get openvpn-as
```

Confirm that the output reports Connected.

Example output:

  Scope: User config (available in all your projects)
  Status: √ Connected
  Type: stdio
  Command: uvx
  Args: as-mcp-server
  Environment:

After the MCP server is connected, start Claude Code and use natural-language prompts to retrieve Access Server information.

Start Claude Code:
```
claude
```
Sign in if needed:
```
/login
```

Ask a read-only question about your Access Server. Examples:

Tell me the Access Server version.

Give me a list of users and groups.

Show me the VPN connection attempts from today.

Give me a list of users that connected to the VPN in the last 7 days.

Show me the VPN authentication failures from today for <USER_NAME>.

Review the response returned from Access Server.
Important
as-mcp-server currently exposes read-only tools. These prompts retrieve information from Access Server; they don't modify its configuration.

Respond to a TOTP MFA prompt⁠

If the administrative account uses TOTP MFA, Claude Code may prompt you for a current code before the MCP server can retrieve information.

Example:

Access Server requires a one-time MFA code for user "mcp-admin".
Please reply with the current 6-digit code from your authenticator app.

Open the authenticator associated with the administrative account.
Enter the current six-digit TOTP MFA code.
Press Enter.
Continue with your query.
- You can reuse the authenticated session as long as the MCP process lasts. Access Server tokens expire every 10 minutes, but the tool renews them in the background. Users are asked for a new code after Access Server's renewal limit, or if the machine sleeps past a token's expiry.

Remove the server from Claude Code⁠

To remove the registered server:
```
claude mcp remove openvpn-as
```

Claude Code currently supports subcommands such as mcp add, mcp get, mcp list, and mcp remove for managing MCP servers.

The essential configuration for another stdio-compatible MCP client is:

Command: uvx
Argument: as-mcp-server

Client commands and configuration formats can change, so refer to the current documentation for your MCP client if these examples no longer match its interface.

Claude Desktop⁠

Open Claude Desktop.
Navigate to Settings → Developer → Edit Config.

Add the following MCP server configuration:

{
  "mcpServers": {
    "openvpn-as": {
      "command": "uvx",
      "args": ["as-mcp-server"]
    }
  }
}

Save the configuration file.
Quit and reopen Claude Desktop.
Important
A window refresh isn't sufficient.

Codex⁠

Configure openvpn-as as a local stdio server that runs uvx as-mcp-server.

For example, in the Codex MCP configuration:

[mcp_servers.openvpn-as]
command = "uvx"
args = ["as-mcp-server"]

Codex CLI⁠

Run:

codex mcp add openvpn-as -- uvx as-mcp-server

VS Code⁠

Run:

code --add-mcp '{"name":"openvpn-as","command":"uvx","args":["as-mcp-server"]}'

VS Code currently supports adding local MCP servers from the command line with --add-mcp.

Gemini CLI⁠

Run:

gemini mcp add -s user openvpn-as uvx as-mcp-server

Cursor⁠

Configure openvpn-as as a local stdio MCP server in Cursor.

Open or create Cursor's global MCP configuration file:
```
~/.cursor/mcp.json
```
Tip
Using the global configuration makes the MCP server available across your Cursor projects. For a project-specific configuration, use .cursor/mcp.json in the project directory.

Add the openvpn-as MCP server:

{
  "mcpServers": {
    "openvpn-as": {
      "type": "stdio",
      "command": "uvx",
      "args": ["as-mcp-server"]
    }
  }
}

Save the file.
Open Cursor and navigate to Customize → MCPs.
Confirm that openvpn-as appears as an available MCP server.
- Cursor uses the stdio transport to start uvx as-mcp-server as a local process.

Alternative: If you use the Cursor CLI, you can register the server from a terminal:

agent mcp add openvpn-as -- uvx as-mcp-server

OpenCode⁠

Open a terminal.
Add openvpn-as to your global OpenCode configuration:
```
opencode mcp add openvpn-as --global -- uvx as-mcp-server
```
Tip
The --global option makes the MCP server available across OpenCode projects. Omit --global if you want to register it for the current project only.
Verify the MCP server connection:
```
opencode mcp list
```
Confirm that openvpn-as reports a connected status.
- For example:
```
✓ openvpn-as  connected
```

You can provide the Access Server connection information through environment variables instead of storing a profile with uvx as-mcp-server setup.

For most local installations, the profile/keyring method is preferable because the operating system's credential store can store the password.

Complete Step 1 to install uv.
Skip Step 2. Don't run uvx as-mcp-server setup.

Windows PowerShell:

claude.cmd mcp add --scope user openvpn-as `
  -e OPENVPN_AS_URL=https://vpn.example.com `
  -e OPENVPN_AS_USER=mcp-admin `
  -e OPENVPN_AS_PASSWORD=<ADMIN_PASSWORD> `
  -- uvx as-mcp-server

macOS or Linux:

claude mcp add --scope user openvpn-as \
  -e OPENVPN_AS_URL=https://vpn.example.com \
  -e OPENVPN_AS_USER=mcp-admin \
  -e OPENVPN_AS_PASSWORD=<ADMIN_PASSWORD> \
  -- uvx as-mcp-server

Continue with Step 4 to verify the Access Server connection.
- Environment variables override values from the stored profile field by field.

You don't need to clone the repository for normal use. uvx as-mcp-server retrieves and runs the published PyPI package.

Clone the repository when you want to inspect or modify the source, contribute changes, or test code not yet released to PyPI.

Open a terminal.
Choose one of the following methods:
- Git — Run the following:
```
git clone https://github.com/OpenVPN/as-mcp-server.git
```
- GitHub CLI — Run the following:
```
gh repo clone OpenVPN/as-mcp-server
```
- Download the ZIP file:
  1. Open the Access Server MCP Server repository.
  2. Select Code.
  3. Select Download ZIP.
  4. Extract the ZIP archive.
  5. In your terminal, change to the extracted directory.

Troubleshooting⁠

Example:

error: Access Server is not configured. Run "uvx as-mcp-server setup" once,
or set OPENVPN_AS_URL, OPENVPN_AS_USER and OPENVPN_AS_PASSWORD in the
MCP server's environment.

Cause: as-mcp-server doesn't have connection information for Access Server.

Resolution: Complete Step 2, or configure the environment variables described in the optional environment-variable section.

Cause: openvpn-as isn't registered with Claude Code at user scope, or it was previously registered with a local scope in a different Claude Code project.

Resolution:

Windows PowerShell:

claude.cmd mcp add --scope user openvpn-as -- uvx as-mcp-server

macOS or Linux:

claude mcp add --scope user openvpn-as -- uvx as-mcp-server

Verify the registration:
```
claude mcp get openvpn-as
```

Cause: You entered an IP address or hostname without the https:// scheme.

Incorrect:

vpn.example.com
203.0.113.10

Correct:

https://vpn.example.com
https://203.0.113.10

Resolution: Run setup again with the complete HTTPS URL.

Example:

Access Server rejected the login for user "mcp-admin" ... (403: Login failed)

Possible causes include:

The administrative username is incorrect or doesn't exist.
The password is incorrect or doesn't exist.
The account doesn't have administrative privileges.

Resolution: Run uvx as-mcp-server setup again with a valid administrative account.

A TOTP MFA failure can occur when:

The six-digit TOTP MFA code is incorrect.
You reuse a code that has already been accepted.
The Access Server host and authenticator device clocks aren't synchronized.
Repeated authentication failures have temporarily locked the account.

TOTP codes are time-sensitive and can only be used once for this authentication flow. Enter the next valid code rather than retrying an expired or previously used code.

If the Access Server rejects a correct TOTP MFA code after repeated failures, stop retrying and review the Access Server logs for an account lockout before continuing. Codes are valid for 30 seconds, and after five failed attempts, the account locks for 15 minutes (Access Server defaults).

Example:

error: TLS certificate verification failed for https://203.0.113.10.

as-mcp-server verifies the Access Server web certificate by default. Use a certificate issued by a trusted certificate authority whenever possible.

For a tutorial to set up certificates for a hostname or public IP address, refer to Tutorial: How to Use ACME Client to Issue Web SSL Certificates for the Access Server UI. Access Server's current ACME workflow supports trusted Let's Encrypt certificates for both domains and public IP addresses.

For testing with a self-signed certificate, you can temporarily turn off certificate verification.

Windows PowerShell:

$env:OPENVPN_AS_INSECURE = "true"
uvx as-mcp-server setup

macOS or Linux:

OPENVPN_AS_INSECURE=true uvx as-mcp-server setup

Example:

error: Access Server did not answer within 30s
(POST /auth/login/userpassword).

Possible causes include:

The Access Server web services aren't reachable from the MCP client host.
TCP 943 isn't reachable, or TCP 443 isn't reachable when web service forwarding is being used.
The configured IP address or hostname is incorrect.
A RADIUS or LDAP server used for authentication is unavailable.
External authentication is misconfigured.
An external RADIUS or LDAP MFA challenge wasn't completed before the timeout.

Resolution: Verify network connectivity and authentication dependencies before increasing OPENVPN_AS_TIMEOUT.

Example:

This profile requires web based SAML authentication.

as-mcp-server doesn't currently support the browser-based SAML authentication flow.

Resolution: Use a dedicated administrative account that authenticates with local, PAM, RADIUS, or LDAP credentials, then run:

uvx as-mcp-server setup

Tutorial: Connect Your AI Agent to Access Server Using the MCP Server⁠

Overview⁠

Use cases⁠

Where the MCP server runs⁠

Prerequisites⁠

Troubleshooting⁠

Related resources⁠

Was this information helpful?