AI Agents (MCP)

WolfStack has a built-in Model Context Protocol server. Point Claude Code, or any other MCP client, at a node and the agent can read that node's state and start, stop or restart its containers and VMs — after you sign in and approve it.

It is off by default and enabled per node. Agents sign in with a real WolfStack account, you approve each app, and the agent can never run commands, open a shell, read files or delete anything.

What an agent can do

Tool	What it does	Permission
get_node_status	Hostname, version, uptime, CPU, memory, load, disks	read
list_cluster_nodes	Nodes you are allowed to see, online state, workload counts	read
list_containers	Docker and LXC containers with state, image and IP	read
get_container_logs	Recent log lines of one container (up to 500), obvious secrets masked	logs
list_vms	Virtual machines with run state, CPU and memory	read
list_inbox_findings	Open Predictive Inbox findings	read
list_backup_schedules, list_backups	Schedules, destinations (type only) and recent backups	read
list_storage_mounts	Mounts with type, mount point and status	read
container_action	Start, stop or restart a container	containers
vm_action	Start, gracefully shut down or restart a VM	vms
run_backup_schedule	Run an existing backup schedule now	backup

There are deliberately no tools for running commands, terminals, files, deleting or destroying anything, networking, firewall, users or settings. Actions go through the same safety checks as the dashboard: a WolfHA standby is never started by hand, and a container or VM whose WolfNet IP is live elsewhere is never started twice.

Apart from container logs, answers never include credentials, environment variables, backup hook commands, VM notes or storage sources — each tool returns a fixed, minimal set of fields. Logs are different: applications print whatever they print, sometimes including passwords. WolfStack masks the obvious ones, but logs are a separate permission (logs) that is never ticked by default — only grant it if you are happy for that text to reach the agent's AI provider.

Turn it on

1. Open Settings → AI Agents (MCP) on the node you want agents to reach.
2. Enter the node's public HTTPS URL — scheme, host and port only, for example https://ws1.example.com:8553. Sign-in tokens are tied to this URL, so changing it later ends every existing approval.
3. Tick Enable MCP on this node and save. The page shows the MCP URL (your URL followed by /mcp) and a ready-made Claude Code command.

HTTPS is required. MCP only answers on a TLS listener. If the node itself serves plain HTTP, put a TLS reverse proxy in front of it on the same machine and use the proxy's address as the public URL; requests from anywhere else over plain HTTP are refused. The proxy must send X-Forwarded-For — without it every client looks like the proxy and shares one set of rate limits and sign-in lockouts.

Each node is enabled separately and serves only its own containers, VMs and backups. To manage several nodes, enable MCP on each and add each one to your agent.

Connect Claude Code

Then run /mcp in Claude Code and choose to authenticate. A WolfStack page opens in your browser:

1. Check the app name and where access is handed to (for Claude Code that is your own computer, localhost).
2. Tick the permissions you want to give — only read is ticked to start with.
3. Sign in with your WolfStack username, password and two-factor code. This is asked every time, even if you are already signed in to the dashboard.
4. Press Approve. Claude Code receives its token and the tools appear.

Any other MCP client that supports remote (Streamable HTTP) servers with OAuth sign-in connects the same way: give it the MCP URL.

Who can grant what

• Admin WolfStack users can grant every permission.
• Viewer WolfStack users can only ever grant read and logs.
• Linux accounts (when sign-in mode allows them) can grant every permission only if they are root or in the sudo / wheel group; other Linux accounts can grant read and logs only.
• Permissions come from the account you actually signed in with. A Linux account never inherits the role of a WolfStack user with the same name, or the other way round.
• Single sign-on and passkey-only accounts can't approve agents, because the approval page needs a password.
• A user restricted to certain clusters can only authorize nodes in those clusters.

These rules are re-checked on every request, not just at sign-in: delete a user, demote them to viewer or remove their cluster access, and their agents lose that access immediately. Changing a user's password or two-factor setup — on any node, since users replicate across the cluster — ends all of their agent approvals.

Managing access

Settings → AI Agents (MCP) lists every approved agent (user, app, permissions, last used, expiry) with a Revoke button, and every registered app with Remove. Revoking takes effect on the agent's next request.

The refresh token an agent uses to renew is replaced on every use. If an old one is presented again later — a sign it was copied — WolfStack ends that approval entirely. Replaying a used sign-in code does the same.

Every tool call, approval, failed sign-in, refused request and rate-limit refusal is recorded in the audit log under Settings → API Keys / Enterprise → Audit Log (entries start with mcp:) and in the WolfStack journal. Each action is logged as it starts as well as when it finishes, so an action is on record even if the agent disconnects mid-call.

Access tokens last 15 minutes. Approvals renew for up to 30 days at a time and end 90 days after they were given, however often they are used.

Unattended agents (API keys)

For an agent with no person to sign in — a scheduled job on a server — an admin can additionally tick Also accept API keys. The agent then sends an API key as Authorization: Bearer wsk_….

• The key must carry the mcp scope, plus read, logs, containers, vms or backup for what the agent may do. A key without mcp is refused — including full-access (*) keys, which give an agent nothing — so existing script keys never become agent keys by accident.
• An API key is a shared secret, not a person: whoever holds it acts as it. Give it an expiry date and prefer OAuth sign-in wherever someone can approve.
• API keys need a licensed WolfStack, as for the REST API.

Security model

• Off until enabled — a node that never enables MCP answers not found on every MCP and sign-in address.
• OAuth 2.1 with PKCE — authorization codes are single-use and expire in 60 seconds; tokens are bound to this node's MCP URL and are useless anywhere else.
• Nothing usable at rest — WolfStack stores only hashes of codes and tokens, in a file readable by root only.
• A fixed public URL — the sign-in server's identity comes from your setting, never from a request header an attacker controls.
• Consent you can read — the approval page names the app (marked unverified), shows exactly where access is sent, warns when that is your own computer, cannot be embedded in another site, and runs no scripts.
• Same sign-in protection as the dashboard — failed sign-ins on the approval page count towards WolfStack's brute-force lockout.
• No browser sessions, no cluster secret — /mcp accepts only MCP tokens (and API keys when enabled), so a malicious web page can't use your logged-in browser to drive it.
• Rate limits on app registration, the approval page, sign-in, token requests, tool calls and especially actions. Behind a TLS reverse proxy on the same machine that sends X-Forwarded-For, limits apply per real client address, not to the proxy.
• Untrusted text is labelled — container logs and finding text come from the systems being managed; tools tell the agent not to follow instructions found in them.

Troubleshooting

You see	Meaning
404 Not Found	MCP is not enabled on that node, or the public URL isn't set.
403 insecure_transport	The request came over plain HTTP from another machine. Use the HTTPS URL.
401 with a sign-in prompt	Not signed in yet, or the approval was revoked or expired — authenticate again with /mcp.
403 insufficient_scope	The tool needs a permission you didn't grant. Re-authorize and tick it (viewers can't grant actions).
"Unknown app" on the approval page	The app's registration expired (unapproved apps are removed after a day) or was removed. Remove and re-add the server in your client.
Approval stopped working after a password change	Expected — password and two-factor changes end all of that user's approvals. Authorize again.