---
title: "Connect an AI agent with MCP"
description: "Connect an AI client to Alpacon through hosted or local MCP. Set up authentication, choose a client, verify the connection, and try your first governed action."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Connect an AI agent with MCP

<span id="getting-started-with-mcp" />

# Connect an AI agent with MCP

There are two ways to connect an AI client to Alpacon over MCP: a hosted server that needs no install, or a local server you run yourself. This guide covers both, then walks through installing the local server, configuring an API token, and connecting it to an AI client.

## Hosted vs local

Alpacon hosts a managed MCP server at `https://mcp.alpacon.io/mcp` using the streamable HTTP transport. Point your AI client at that URL and sign in through your browser—no install and no API token required.

The Alpacon web console's Connect your AI agent dialog also offers one-click install for Cursor and VS Code.

**Why use the hosted server**:

- **No install**: no `uvx`, no Python, no local process to keep running
- **No API token**: you authenticate through your browser (OAuth) instead of pasting a token into a config file
- **No region or workspace config**: the workspaces you can access come from your login, so you name the workspace in your prompt instead (for example, "list servers in the production workspace")
- **Always up to date**: runs the latest tools without upgrading anything

### How authentication works

The first time your client connects, it opens a browser window to sign in to Alpacon. After you sign in, the client receives a short-lived token and uses it for every request, with the same identity, RBAC, and audit trail as the Alpacon web console. If your session needs MFA re-verification (for example after an MFA timeout), the client automatically reopens the browser to complete it.

Because access comes from your login, you don't set a region, workspace, or API token in your client config. Instead, name the workspace in your prompt (for example, "in the production workspace"), and the region is resolved automatically from your authorized workspaces.

See [connect your client](#connect-your-client) below for the exact configuration for each client.

## Prerequisites

The prerequisites and steps below are for running the server locally. If you'd rather not install anything, see the hosted server section above.

- **Python 3.12 or later**
- **[uv](https://docs.astral.sh/uv/)**, which provides the `uvx` command used to run the server without a manual install:

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

- An Alpacon workspace and a token. To create a personal API token, click your account card at the bottom of the left sidebar and select **My API tokens**. For command execution and file transfers, see the [service-token requirements](/use/iam/applications/service-tokens/).

New personal API tokens cannot hold command-execution or file-transfer scopes. Existing tokens with those scopes keep working without a work session. Use a [service token](/use/iam/applications/service-tokens/) for automation and CI.

## Quick start

### Run the setup wizard

```bash
uvx alpacon-mcp
```

If no token is configured yet, this drops straight into an interactive setup wizard. It asks for:

1. **Region** (default: `ap1`)
2. **Workspace** name
3. **API token** (hidden input)

It then saves the configuration, tests the connection, and prints the MCP client config to copy. If a token is already configured, the same command starts the server directly instead of running the wizard.

You can also run the wizard explicitly at any time:

```bash
uvx alpacon-mcp setup
```

### Add the config to your client

Copy the printed configuration into your MCP client (see [connect your client](#connect-your-client) below), then restart or reconnect the client.

### Verify the connection

```bash
uvx alpacon-mcp test
```

Prompts for a region and workspace, looks up the matching token, and confirms the API is reachable.

### Other setup commands

```bash
uvx alpacon-mcp                                # Start the server (runs setup if no token exists)
uvx alpacon-mcp setup                          # Run the interactive setup wizard
uvx alpacon-mcp setup --local                  # Save to ./config/token.json instead of the global location
uvx alpacon-mcp setup --token-file ~/my.json   # Save to a custom file path
uvx alpacon-mcp test                           # Test the connection for a region/workspace
uvx alpacon-mcp list                           # Show all configured workspaces
uvx alpacon-mcp add                            # Add another workspace to an existing config
```

`setup`, `test`, `list`, and `add` also accept `--config-file <path>` on the top-level command to point at a specific token file for that invocation.

## Connect your client

Each client can connect to the hosted server (remote) or to a local `uvx alpacon-mcp` process. Pick your client:

  
    **Remote (hosted)**

    ```bash
    claude mcp add --transport http alpacon https://mcp.alpacon.io/mcp
    ```
    On first use, Claude Code opens your browser to sign in. Verify with `claude mcp list`.

    **Local**

    Add the server with the CLI:

    ```bash
    claude mcp add alpacon -- uvx alpacon-mcp
    ```

    Or add the same JSON shown for Claude Desktop to a project-level `.mcp.json`. Verify with `claude mcp list`.
  
  
    **Remote (hosted)**

    Add a custom connector: **Settings → Connectors → Add custom connector**, with the URL `https://mcp.alpacon.io/mcp`.

    For clients that only support local servers, use the `mcp-remote` bridge in `claude_desktop_config.json` instead:

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.alpacon.io/mcp"]
        }
      }
    }
    ```

    **Local**

    Edit the config file:
    - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  
  
    **Remote (hosted)**

    Create `~/.cursor/mcp.json`:

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "url": "https://mcp.alpacon.io/mcp"
        }
      }
    }
    ```

    **Local**

    Create `~/.cursor/mcp.json`:

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  
  
    **Remote (hosted)**

    Create `.vscode/mcp.json`:

    ```json
    {
      "servers": {
        "alpacon": {
          "type": "http",
          "url": "https://mcp.alpacon.io/mcp"
        }
      }
    }
    ```

    **Local**

    Install the MCP extension, then create `.vscode/mcp.json`:

    ```json
    {
      "servers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  
  
    **Remote (hosted)**

    Any MCP client that supports remote or streamable HTTP servers can connect using this URL:

    ```
    https://mcp.alpacon.io/mcp
    ```

    **Local**

    Any MCP client that supports the stdio transport can run the server directly:

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  

## First steps

<span id="token-configuration" />
<span id="transports" />
<span id="choose-toolsets" />

For transport, token and toolset options, see [MCP configuration](/reference/mcp/configuration/).

Once your client is connected, try asking it:

- "List my servers"
- "Show CPU usage for web-01 over the last hour"
- "Who am I logged in as?"

See the [tools](/reference/mcp/tools/) for the full list of what the agent can do, grouped by category.

Source: https://docs.alpacax.com/integrate/mcp/