MCP tools
Alpacon’s MCP tools map natural language requests—“restart nginx on web-01,” “who has sudo on the production fleet,” “what changed on db-02 last night”—onto 159 typed operations across 11 categories. This page covers the conventions shared by every tool, the three general tools that don’t belong to any single category, and a map of the categories themselves.
All tools accept workspace (required) and region (optional, defaults to the configured region), except the three general tools below—each documents its own parameters. These common parameters are omitted from the tables on every category page.
Access levels
Every tool is annotated with one of four access levels, so a client or a human reviewing a transcript can tell at a glance what a call might do before it runs.
| Level | Meaning |
|---|---|
| Read-only | Lists or retrieves data. Never changes state. |
| Additive | Creates or executes something new (a note, a command, a token) without touching existing resources. |
| Idempotent write | Updates an existing resource. Calling it again with the same input leaves the resource in the same state. |
| Destructive | Deletes, reboots, shuts down, revokes, or otherwise removes or disrupts a resource. Not always reversible. |
Work Sessions
Tools that mutate infrastructure—running a command, transferring a file—accept a work_session_id parameter. When a caller connects through MCP OAuth or a browser session, the Alpacon server requires that call to be linked to an active Work Session; static API tokens and service tokens bypass this requirement. If work_session_id is omitted, the server falls back to the ALPACON_WORK_SESSION environment variable when one is set. Each affected tool’s own page notes this explicitly.
General tools
These three tools sit outside the 11 categories: they’re the entry points for discovering workspaces, checking identity, and checking the server itself.
| Tool | Description | Access |
|---|---|---|
list_workspaces | List available workspaces and their regions | Read-only |
get_current_user | Get the currently authenticated user’s identity | Read-only |
health_check | Check MCP server health and connectivity | Read-only |
list_workspaces
List all available workspaces and their regions—the domain hostname for each, and whether a token is configured. This is the tool to call first: almost every other tool needs a workspace value from its result.
Access: Read-only
Unlike every other tool on this page, list_workspaces does not take a workspace parameter—it’s how you discover which workspaces exist in the first place.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
region | string | No | Filter to a single region (for example ap1). Omit to list workspaces across all configured regions |
Example
“What workspaces do I have access to?”
Returns each configured workspace with its region and domain, so you can pick the right workspace value for subsequent calls.
get_current_user
Get the currently authenticated user for this call: username, email, role, UID, shell, and home directory. Use this to confirm identity before a privileged action, or to answer “who am I” questions.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
workspace | string | Yes | Workspace name |
region | string | No | Region (ap1, us1, eu1). Auto-detected if omitted |
Example
“Who am I logged in as?”
Returns the authenticated user’s username, email, and role for the current workspace.
health_check
Check MCP server health: version, uptime, authentication mode, and connection pool info. Useful as a first call to confirm the server is running and reachable before issuing other requests. Takes no parameters at all—not even workspace.
Access: Read-only
Example
“Is the MCP server up?”
Returns version, uptime, and connectivity status without touching any Alpacon workspace.
Categories
Operate
| Category | Tools | Description |
|---|---|---|
| Server management | 21 | Server inventory, notes, agent lifecycle, system control, registration tokens |
| Command execution | 3 | Run shell commands on one or more servers, review command history |
| File transfer | 10 | Upload and download files and folders over WebFTP |
| System information & packages | 15 | Hardware, OS, users, groups, network, disk, and package management |
Observe
| Category | Tools | Description |
|---|---|---|
| Monitoring & alerts | 14 | CPU, memory, disk, and network metrics; alert rules |
| Events & webhooks | 11 | Server event log, event subscriptions, webhook endpoints |
| Audit logs | 6 | Activity logs, server and WebFTP transfer logs, AI security analysis |
Govern
| Category | Tools | Description |
|---|---|---|
| Work Sessions | 8 | Create, inspect, extend, and close the approval-gated sessions that scope infrastructure actions |
| Access control & approvals | 18 | Command, server, and file ACLs; approval requests; sudo policies |
| IAM & API tokens | 29 | Workspace users, groups, memberships, machine applications, API tokens |
| Certificates | 21 | Certificate authorities, signing requests, issued certificates, revocation |