Getting started 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 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, which provides the uvx command used to run the server without a manual install:

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

• An Alpacon workspace and an API token. Log in to your workspace, open API Token in the sidebar, and create a token. Command execution and file transfer tools also need ACL permissions configured on that token.

Quick start

uvx alpacon-mcp

uvx alpacon-mcp setup

uvx alpacon-mcp test

Other setup commands

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.

Token configuration

Tokens are stored as JSON, keyed by region and then workspace:

{
  "ap1": {
    "production": "alpat-xxxxxxxxxxxxxxxxxx",
    "staging": "alpat-xxxxxxxxxxxxxxxxxx"
  }
}

Default location: ~/.alpacon-mcp/token.json (falls back to ./config/token.json if the global file doesn’t exist).

Resolution order when the server looks up a token:

1. ALPACON_MCP_CONFIG_FILE environment variable, if set—points at a specific file
2. The global config, if it exists
3. The local config (./config/token.json)

Connect your client

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

claude mcp add --transport http alpacon https://mcp.alpacon.io/mcp

claude mcp add alpacon -- uvx alpacon-mcp

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

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

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

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

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

{
  "servers": {
    "alpacon": {
      "command": "uvx",
      "args": ["alpacon-mcp"]
    }
  }
}

https://mcp.alpacon.io/mcp

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

Transports

uvx alpacon-mcp runs the stdio transport, the default for local clients above. Two other transports are available for different deployment shapes:

• SSE (alpacon-mcp-sse console script): Server-Sent Events over HTTP, for local network integrations that need an HTTP endpoint instead of a spawned process.
• Streamable HTTP (alpacon-mcp-http console script): this is the transport behind the hosted server described earlier. It authenticates callers through Auth0 (OAuth) instead of a static token file, so a client signs in through the browser instead of storing an API token locally.

Most individual users only need the default stdio setup above; the other transports matter mainly if your organization self-hosts a shared MCP endpoint.

First steps

Once your client is connected, try asking it:

• “List my servers”
• “Show CPU usage for web-01 over the last 24 hours”
• “Who am I logged in as?”

See the tools for the full list of what the agent can do, grouped by category.