Server management tools
These tools cover everything about the servers themselves: finding and updating server records, keeping notes on them, controlling the Alpacon agent, and enrolling new hosts with registration tokens. They answer requests like “which servers do we have,” “restart the agent on web-01,” or “give me an install script for a new Debian box.”
Rebooting, shutting down, or upgrading the operating system underneath a server isn’t available through MCP. Run the command inside a Work Session instead—see Command execution tools.
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
list_servers | List all servers in a workspace | Read-only |
get_server | Get detailed information about one server | Read-only |
get_collection_profile | See what a server collects and at what cadence | Read-only |
update_server | Rename or relabel a server, or toggle its offline alert | Idempotent write |
unregister_server | Remove a server from the workspace | Destructive |
star_server | Pin or unpin a server for quick access | Idempotent write |
list_server_notes | List documentation notes on a server | Read-only |
create_server_note | Add a documentation note to a server | Additive |
get_server_note | Get a single server note | Read-only |
update_server_note | Update an existing server note | Idempotent write |
delete_server_note | Delete a server note | Destructive |
restart_agent | Restart the Alpacon agent | Destructive |
upgrade_agent | Upgrade the Alpacon agent to the latest version | Destructive |
update_information | Refresh collected hardware, OS, network, and package data | Additive |
list_registration_tokens | List Alpamon registration tokens | Read-only |
create_registration_token | Mint a new registration token | Additive |
delete_registration_token | Revoke a registration token | Destructive |
get_registration_guide | Get the platform-specific install script | Read-only |
Server inventory
Discover, rename, pin, and remove servers from the workspace inventory.
list_servers
List all servers in a workspace, returning name, UUID, status, OS, and connection info for each. Use this first to discover available servers and to obtain the UUIDs required by nearly every other server tool.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of results per page, up to 100 |
Results are paginated at 15 per page by default. Compare the response’s count against the number of results and follow the next page number—or pass a larger page_size (max 100)—to see every server.
Example
“What servers do I have in production?”
Returns the full server inventory so you can find the one you need by name, OS, or status.
get_server
Get detailed information about a specific server by its UUID, including hostname, IP address, OS, agent version, and online status. Look up the UUID with list_servers first if you don’t already have it.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Show me the details for web-01”
Looks up the UUID via list_servers, then fetches hostname, IP, OS, and status for that one server. For a fuller picture that includes hardware and OS internals, see System information tools.
get_collection_profile
See what a server collects and at what cadence: the always-on core families (such as the disk-usage alert, with the latest reading per volume), the metrics families the workspace’s plan unlocks (each with its retention period), and the families that aren’t collected on this workspace at all, with why and what plan unlocks them. Unlike the metric-data tools, this answers on every plan, so it’s the way to check whether a family is collected before asking for its data—or to explain an empty chart.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Why is db-02’s disk I/O chart empty?”
The agent calls get_collection_profile and finds disk-io listed under the families this workspace doesn’t collect, with the reason and the plan that would unlock it—explaining the empty chart without a wasted call to get_disk_io.
update_server
Rename or relabel a server’s name or description by UUID, or toggle its own offline-alert delivery with offline_alert_enabled. This only updates Alpacon’s inventory metadata—it doesn’t change anything on the host itself. At least one field must be provided.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
name | string | No | New server name |
description | string | No | New server description |
offline_alert_enabled | boolean | No | This server’s own offline-alert toggle, independent of any workspace-wide alert rule. Defaults to true. Only a caller who can manage the server may change it, and the server’s own agent credential is refused regardless |
Example
“Rename server 7e3984de-49ab-4cc6-bcdf-21fbd35858b8 to web-01-tokyo”
Updates the server’s display name in the inventory; the host itself is unaffected.
“This server is going into planned maintenance for the weekend—stop alerting on it going offline”
The agent calls update_server with offline_alert_enabled=false. Re-enable it with the same call once the server is back.
unregister_server
Remove a server from the workspace by UUID. The server disappears from all listings and can no longer be targeted by new Work Sessions, but the Alpamon agent keeps running on the host until it’s uninstalled there. This can’t be undone from this tool—re-enrolling the host requires running the install script with a registration token again.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Unregister the decommissioned db-old server”
Confirm the UUID with get_server first—once unregistered, restoring the entry requires re-running the install script on the host.
star_server
Pin or unpin a server for the caller’s own faster access. This is a personal-preference flag, not a fleet-wide setting—it doesn’t change visibility, RBAC, or ACLs for anyone else.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
status | boolean | Yes | true to pin, false to unpin |
Example
“Star web-01 so I can find it faster”
Pins the server for the caller only; nobody else’s view of the inventory changes.
Server notes
Attach and manage freeform documentation on a server: maintenance logs, configuration notes, operational records.
list_server_notes
List documentation notes attached to a server, including titles, content, and timestamps. Use this to review existing operational records before adding new ones.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“What notes do we have on db-01?”
Returns every note recorded against that server.
create_server_note
Create a documentation note on a server with a title and content body. Use this to record operational notes, maintenance logs, or configuration documentation.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
title | string | Yes | Note title |
content | string | Yes | Note content |
Example
“Add a note to web-01: rotated the TLS cert on 2026-07-09”
Creates a new note attached to that server.
get_server_note
Get detailed information about a specific server note by its ID, including title, content, server, author, timestamps, and privacy settings. Look up the note ID with list_server_notes first.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
note_id | string | Yes | Note ID |
Example
“Show me the full content of that maintenance note”
Fetches the full detail of one note once you have its ID from list_server_notes.
update_server_note
Update an existing server note’s title or content by ID. This is a partial update—only the fields you provide are changed. At least one of title or content must be provided.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
note_id | string | Yes | Note ID |
title | string | No | New title |
content | string | No | New content |
Example
“Update that note to say the cert rotation is complete”
Only the content field changes; the title stays as-is unless you also pass a new one.
delete_server_note
Permanently delete a server note by its ID. This action cannot be undone.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
note_id | string | Yes | Note ID |
Example
“Delete the outdated maintenance note on db-01”
Confirm the note with get_server_note before deleting—there’s no undo.
Agent lifecycle
Control the Alpacon agent (Alpamon) running on a server, and trigger it to refresh the system information it reports.
restart_agent
Restart the Alpacon agent process on a server. The agent briefly goes offline during the restart. Use this when the agent is unresponsive or after configuration changes.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Restart the agent on web-01, it’s not reporting metrics”
Restarts the agent process; the server briefly shows offline until it reconnects.
upgrade_agent
Upgrade the Alpacon agent on a server to the latest available version. The agent briefly restarts during the upgrade.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Upgrade the agent on web-01 to the latest version”
Triggers the upgrade on that server; loop over list_servers results to upgrade a whole fleet.
update_information
Refresh a server’s system information by triggering the agent to re-collect hardware, OS, network, and package data. Use this after hardware changes or OS updates so the dashboard reflects the current state.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Refresh the info for web-01 after the RAM upgrade”
Triggers a re-scan; updated data appears once the agent finishes collecting it.
Registration tokens & install guide
Issue and manage the tokens used to enroll new hosts, and fetch the platform-specific install script that uses them.
list_registration_tokens
List Alpamon registration tokens issued in the workspace—credentials embedded in the install script that authenticate a host on first run. Use this before issuing a new token or rotating a compromised one.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of results per page |
Example
“What registration tokens do we have active?”
Returns token IDs, names, and creation metadata for the workspace.
create_registration_token
Mint a new Alpamon registration token for installing the agent on a new host. The returned token is embedded in the install script (see get_registration_guide). Name tokens by cohort or batch (for example, prod-web-2026-q2) for clean rotation later.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Token name |
description | string | No | Token description |
Example
“Create a registration token for the new batch of web servers”
Mints a token you can pass straight into get_registration_guide.
delete_registration_token
Revoke an Alpamon registration token by ID. Already-enrolled hosts keep working—this only blocks future enrollments using the same token. Use this to rotate credentials after a suspected leak or once a rollout cohort is complete.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | Registration token UUID |
Example
“Revoke the token we used for last quarter’s rollout”
Blocks new installs with that token; hosts already enrolled are unaffected.
get_registration_guide
Get the platform-specific Alpamon install script for a registration token—the exact commands to run on the target host to bring it under Alpacon’s control. platform must be one of debian, rhel, darwin, or windows. Optionally pre-name the host with server_name.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | Registration token UUID |
platform | string | Yes | One of debian, rhel, darwin, windows |
server_name | string | No | Server name to pre-configure during installation |
Example
“Give me the install script for a new Debian server named web-05”
Returns the install commands for that token, pre-configured to name the host web-05.