---
title: 'Tutorial: Connect Your AI Agent to Access Server Using the MCP Server'
canonical: https://openvpn.net/as-docs/v3/tutorials/tutorial--access-server-mcp-server/
product: Access Server Docs
description: Set up the OpenVPN Access Server MCP Server to let AI agents like Claude Code, Claude Desktop, Cursor, and VS Code query your VPN server in natural language — covers uv installation, connection setup, AI agent registration, and troubleshooting common errors.
---

# 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](https://github.com/OpenVPN/as-mcp-server/).

> **Important**
>
> **Data privacy note**
>
> The MCP tool shares responses with the AI model provider. This includes usernames, IP addresses, log entries, and config values. TOTP secrets, the subscription key, and secret-looking config values are redacted.

### 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](https://openvpn.net/as-docs/v3/tutorials/tutorial--turn-on-mfa.md). Access Server supports built-in TOTP MFA with local, PAM, LDAP, and RADIUS authentication.

> **Important**
>
> Use a dedicated administrative account for the MCP server rather than sharing another administrator's credentials.
>
> SAML authentication isn't supported by `as-mcp-server` at this time. The MCP server authenticates with a username and password and can complete the additional Access Server TOTP MFA step when enabled.

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.

> **Note**
>
> In our documentation, we use example IPv4 addresses and subnets [reserved for documentation](https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv4), such as `192.0.2.0/24`, `198.51.100.0/24`, and `203.0.113.0/24`.
>
> Ensure you replace them with valid IPv4 addresses and subnets for your network(s).

## Step 1: Install uv

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

1. Open PowerShell, Command Prompt, or a terminal on the machine where you'll run your MCP client.
2. 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
     ```
3. Close and reopen your terminal so the updated `PATH` takes effect.
4. Verify the installation:

   ```
   uv --version
   ```

> **Tip**
>
> `uvx` is an alias for `uv` tool run. When you later run `uvx as-mcp-server`, `uv` retrieves the published package and runs it in an isolated environment.

## Step 2: Store the Access Server connection information

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.

1. 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.
2. Run the interactive setup:

   ```
   uvx as-mcp-server setup
   ```
3. Enter the Access Server URL when prompted.
4. Enter the Admin username.
5. Enter the Password. The password input is hidden.
6. 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
     ```

> **Tip**
>
> The server also answers RADIUS, LDAP, and PAM challenges, such as a PIN or Duo passcode.

### 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
```

## Step 3: Register the MCP server with Claude Code

Register `as-mcp-server` with Claude Code so it can launch the MCP server when needed.

> **Tip**
>
> This procedure registers the server at **user scope**, which makes it available across your Claude Code projects.

1. 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.
2. 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.

## Step 4: Verify the Access Server connection

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

1. 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
     ```
2. 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.

## Step 5: Verify the MCP server connection in Claude Code

Confirm that Claude Code can launch the registered MCP server.

1. Run:

   ```
   claude mcp get openvpn-as
   ```
2. 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:
     ```

## Step 6: Query Access Server in natural language

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

1. Start Claude Code:

   ```
   claude
   ```
2. Sign in if needed:

   ```
   /login
   ```
3. 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>.
   ```
4. 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.
```

1. Open the authenticator associated with the administrative account.
2. Enter the current six-digit TOTP MFA code.
3. Press Enter.
4. 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

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

## Optional: Register the MCP server with another client

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

1. Open Claude Desktop.
2. Navigate to **Settings → Developer → Edit Config**.
3. Add the following MCP server configuration:

   ```
   {
     "mcpServers": {
       "openvpn-as": {
         "command": "uvx",
         "args": ["as-mcp-server"]
       }
     }
   }
   ```
4. Save the configuration file.
5. Quit and reopen Claude Desktop.

   > **Important**
   >
   > A window refresh isn't sufficient.

> **Tip**
>
> If the configuration file already contains other MCP servers, make a backup before editing it and add `openvpn-as` without removing the existing entries.

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

1. 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.
2. Add the `openvpn-as` MCP server:

   ```
   {
     "mcpServers": {
       "openvpn-as": {
         "type": "stdio",
         "command": "uvx",
         "args": ["as-mcp-server"]
       }
     }
   }
   ```
3. Save the file.
4. Open Cursor and navigate to **Customize → MCPs**.
5. 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
```

> **Note**
>
> The Cursor CLI and editor share the same MCP configuration.

### OpenCode

Register `as-mcp-server` as a local MCP server in OpenCode.

1. Open a terminal.
2. 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.
3. Verify the MCP server connection:

   ```
   opencode mcp list
   ```
4. Confirm that `openvpn-as` reports a connected status.
   - For example:

     ```
     ✓ openvpn-as  connected
     ```

> **Note**
>
> OpenCode treats `openvpn-as` as a local MCP server and starts `uvx as-mcp-server` when it needs to use the Access Server tools.

## Optional: Configure the connection with environment variables

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.

> **Important**
>
> When you configure credentials as MCP environment variables, the administrative password may be stored in your MCP client's configuration. Protect that configuration file and don't commit it to source control.

1. Complete Step 1 to install `uv`.
2. Skip Step 2. Don't run `uvx as-mcp-server setup`.
3. Register the MCP server with the Access Server environment variables:
   - 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
     ```
4. Continue with Step 4 to verify the Access Server connection.
   - Environment variables override values from the stored profile field by field.

## Optional: Clone the as-mcp-server repository

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.

1. Open a terminal.
2. 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](https://github.com/OpenVPN/as-mcp-server/).
     2. Select **Code**.
     3. Select **Download ZIP**.
     4. Extract the ZIP archive.
     5. In your terminal, change to the extracted directory.

## Troubleshooting

### error: Access Server URL is required.

**Cause:** You left the Access Server URL empty during `uvx as-mcp-server setup`.

**Resolution:** Run the setup command again and enter the complete HTTPS URL. Example:

```
https://vpn.example.com
```

### error: Admin username is required.

**Cause:** You didn't provide an administrative username.

**Resolution:** Run setup again and enter an existing Access Server account with administrative privileges.

### error: A password is required.

**Cause:** You left the administrative password empty.

**Resolution:** Run setup again and enter the administrative account password.

### error: The answer (totp\_code) is empty; nothing was sent to the server.

**Cause:** TOTP MFA is enabled, but you didn't provide the requested code.

**Resolution:** Enter the current six-digit TOTP MFA code from the administrator's authenticator.

For TOTP MFA configuration, refer to [Tutorial: Turn On TOTP Multi-Factor Authentication](https://openvpn.net/as-docs/v3/tutorials/tutorial--turn-on-mfa.md).

### error: Access Server is not configured…

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.

### No MCP server named "openvpn-as".

**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:**

1. Register it at user scope:
   - 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
     ```
2. Verify the registration:

   ```
   claude mcp get openvpn-as
   ```

### OPENVPN\_AS\_URL must start with https://

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

### Access Server rejects the administrative credentials

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.

### Credentials rejected for non-administrative account

Example:

```
User "…" authenticated but is not an administrator
```

**Resolution:** Ensure you use an account with administrative privileges.

### Access Server rejects the TOTP MFA code

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

### TLS certificate verification fails

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](https://openvpn.net/as-docs/v3/tutorials/tutorial--acme-web-ssl-certificates.md). 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
  ```

> **Important**
>
> `OPENVPN_AS_INSECURE=true` disables TLS certificate verification. Use it only for temporary testing in an environment you trust. Don't use it as the normal configuration for an administrative connection.

### Access Server doesn't answer within 30 seconds

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

### SAML authentication fails

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
```

## Related resources

- [APIs and Automation](https://openvpn.net/as-docs/v3/tutorials/apis-and-automation.md)
- [Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0](https://openvpn.net/as-docs/v3/tutorials/tutorial--test-the-new-web-api--openapi--in-access-server-3-0.md)
- [Tutorial: An Intro to the sacli Command-Line Utility](https://openvpn.net/as-docs/v3/tutorials/tutorial--sacli-command-line-tool.md)

---

Prev: [Tutorial: Deploy Access Server on AWS with Terraform](https://openvpn.net/as-docs/v3/tutorials/tutorial--deploy-access-server-aws-terraform.md)
Next: [Key Terms](https://openvpn.net/as-docs/v3/tutorials/glossary.md)
Index: https://openvpn.net/as-docs/llms.txt