---
title: "Give AI agents governed access"
description: "Give AI agents governed access to servers. Connect through MCP, scope their tasks, review approvals, and inspect the activity they leave in session records."
---

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

# Give AI agents governed access

You've decided to let an AI agent touch your infrastructure. Maybe it's Claude fixing a failing service, Cursor running a migration, or a custom agent doing routine maintenance. The question isn't *whether* to give it access, but how to grant that access without handing over a standing key you can't take back.

This page is the journey for the person making that decision: a workspace admin or team lead introducing an agent. It walks the whole arc—connect the agent, scope it to the task in front of it, keep a human on the approval, watch it work, and read back everything it did—linking each step to the page that covers it in full. If the concept is new to you, first read [AI agents](/learn/key-concepts/ai-agents/) for the model, then come back here to wire one up.

---

## The model in one paragraph

An AI agent is a first-class actor in Alpacon, governed the same way a person is: it doesn't connect to a server directly, it opens a scoped, time-bound, recorded [work session](/use/work-sessions/) and works inside it. But the agent is held to a **stricter** rule than a human. A person with the Superuser role who requests a session for themselves is approved automatically; **an agent's session requires a human approval by default, even when a Superuser makes the request.** By default there is no automatic path for a non-human actor. That single asymmetry is the heart of agent governance in Alpacon—everything below is how you set it up and live with it.

  A Superuser's own session request clears immediately. A session **requested by an AI agent** does not: by default it waits for a person to approve it. See [Approvals](/use/approvals/#automatic-approval) and [Request a session](/use/work-sessions/create/).

---

## Step 1: Connect the agent

Agents reach Alpacon over **MCP (Model Context Protocol)**, and there are two paths:

- **Hosted**: point your MCP client at `https://mcp.alpacon.io/mcp` and sign in through your browser. No install, no API token pasted into a config file; the agent authenticates with your login and inherits your identity, roles, and audit trail.
- **Local**: run the Alpacon MCP server yourself with `uvx alpacon-mcp`, configured with an API token, for setups that prefer a local process.

For Claude Code, the hosted path is a single line:

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

On first use the client opens your browser to sign in, and you verify with `claude mcp list`. Rather than repeat every client's configuration here, use [Getting started with MCP](/integrate/mcp/) for Claude Desktop, Cursor, VS Code, and the local-server setup, and the [MCP reference](/reference/mcp/) for the full tool catalog. The point for this journey: connecting an agent hands it no SSH key and no VPN credential—it works through the same governed identity layer as the web console and CLI.

---

## Step 2: Scope it down to the task

Connecting an agent doesn't grant it anything on its own. Access is bounded in layers, and each layer is something you control before the agent ever runs a command:

- **Workspace membership**: the agent acts through an Alpacon identity: a person it works on behalf of, or an [application](/use/iam/applications/) created for automation. It can only ever see the one workspace that identity belongs to.
- **Group-based server eligibility**: inside the workspace, [group membership](/use/iam/groups/) decides which servers the identity can even request. A server with no groups assigned to the identity is invisible to it. This is the same join you set up for people; see [Control server access](/use/servers/groups/).
- **Session scope**: to actually do work, the agent opens a [work session](/use/work-sessions/create/) that declares its intent, the specific servers, the features it needs (file transfer, command execution, port forwarding, code editor, privilege elevation), and an expiry. The web terminal is for people: a session requested by an agent can't include it. The scope is a hard ceiling: an action outside it is refused, and the session ends on its own when the time is up.

The discipline that makes this work is **request per task, not standing breadth**. Don't wire an agent into every group and let it open four-hour all-feature sessions by habit. Give its identity the groups the work actually needs, and let each session ask for just the servers, features, and window that one task requires. Least privilege is the default here—the agent only gets what it asks for, and only for as long as it asked. See [Work sessions](/use/work-sessions/) for the full model.

---

## Step 3: The approval moment

Because an agent's session waits for a person by default, someone on your team sees the request. For a work session, the reviewer opens it from the [Approvals](/use/approvals/) queue and sees the requester's justification, the requested duration, the target servers, and the features being asked for. The AI usually reviews the request too: it rates the risk level (Low, Medium, High, or Critical), flags access it thinks the session doesn't need or that the request leaves out, and marks the unneeded features so the reviewer can remove them with one click. Its reasoning is kept on the request for the reviewer to read. When the AI can't review a request, the risk is rated by keywords alone, without these findings.

The reviewer isn't limited to a yes/no. Before approving, they can **tighten the scope**: remove requested features or servers, narrow the run-as account when one was requested and the session is not assigned to a token, shorten the window, and attach recommendations the agent's operator sees before the session starts. So the approval moment is also a scoping moment—an over-broad agent request can be trimmed to exactly what the task warrants and then approved. See [Reviewing requests](/use/approvals/reviewing/) and [Request types](/reference/approvals/#work-session) for what's adjustable per request type.

For the reviewer's side of this—how to read an agent request and decide quickly—see the [approver's guide](/learn/approver-guide/), the counterpart to this page written for whoever holds the queue.

---

## Step 4: Watch it work

Once a session is approved and active, you don't have to wait for it to end to see what's happening. [Live activity](/use/live-activity/) (for the Admin and Superuser roles) shows each active session as it happens: requests waiting on a decision, the command running now with its output, and everything the session has done (commands, terminals, sudo requests and grants, file transfers), searchable and filterable by type and status.

Two things stay in a person's hands while the session runs:

- **Sensitive actions are held while they happen.** High-risk commands don't just run—they're held for a human approver and run only once approved. Privilege elevation (sudo) that the session's sudo policy doesn't cover is refused at once. When a person can clear the refusal, the agent runs the command again after they act; when nobody can, the same command gets the same answer, so the agent doesn't retry it. A misled or jailbroken agent can't quietly escalate, because there's no standing privilege for it to reach for.
- **You can intervene.** From the live view you can **End session** to stop a session immediately, or **Revoke** one that was approved but shouldn't proceed. Every command and transfer is recorded as it runs, so nothing is happening off the record.

---

## Step 5: Read back everything it did

When the work is done, the whole session is there to review—which matters more for a non-human actor than a human one, because accountability can't rest on "I remember what I ran." [Audit](/use/audit/) keeps the complete record:

- **Sessions**: every work session on one list ([Session history](/use/audit/sessions/)), with the **Assignee** column naming who ran it: a person, an AI agent, or a token. A type filter narrows the list to agent sessions, and each row shows how the session ended and its risk level; open it for who approved it and what was in scope.
- **The timeline and recordings**: a session's detail replays a chronological timeline of its commands, terminals, sudo grants, and file transfers, with masked terminal recordings you can play back. See [After a session](/use/audit/sessions/review/).
- **AI post-analysis**: once a session ends, Alpacon adds an AI risk analysis: a risk level, a plain-language summary, an attack-chain and threat check, and recommended verifications. This is the deeper, after-the-fact judgment that complements the live feed in Step 4.

Because people, pipelines, and agents all run through the same work-session model, their activity lands on **one timeline**. When someone asks "what happened on prod-web-1 last night?", the answer is a single record that mixes human commands, agent actions, and CI runs—not separate logs to stitch together. That shared timeline is what makes an agent's actions accountable to the same standard as a person's.

---

## What an agent can't do

The governance model closes the obvious escape hatches. An agent **cannot approve its own work**: a session it requests needs a human by default, even when the requesting identity is a Superuser. It **cannot approve through its own channel** either—a request can't be approved from the same channel it was submitted from, so an agent working through the CLI or MCP can't turn around and clear its own request; approval happens in the web console or Slack, by one of the request's approvers. And it **cannot stand in for a person's identity checks**: steps that require a human's multi-factor verification can't be satisfied by an agent, so they escalate to a real person instead of proceeding. See [sudo with MFA](/use/work-sessions/terminal/sudo-with-mfa/).

One nuance worth understanding, not hiding: **the work-session gate depends on how the agent authenticates.** When an agent connects through browser sign-in (MCP OAuth)—the recommended path above—infrastructure-mutating actions like running commands and transferring files must be linked to an active, approved work session. From December 1, 2026 (00:00 UTC), an existing personal API token with command-execution or file-transfer scopes needs an active, approved work session to create commands or REST file transfers. See [Token restrictions](/use/settings/api-tokens/#token-restrictions). For automation, issue a service token to an [application](/use/iam/applications/) so its activity is scoped and attributed. Keep interactive agents on browser sign-in. See the [MCP reference](/reference/mcp/#governance-model) for exactly which calls are session-scoped.

---

## Where to go next

- [AI agents](/learn/key-concepts/ai-agents/)—the concept behind this journey
- [Zero trust](/learn/key-concepts/zero-trust/)—why Alpacon removes standing access
- [Getting started with MCP](/integrate/mcp/)—connect Claude, Cursor, and VS Code
- [Work sessions](/use/work-sessions/)—request, scope, and approve access
- [Approvals](/use/approvals/)—the queue where an agent's session is reviewed
- [Audit](/use/audit/)—the record of everything an agent did
- [Set up your workspace](/learn/admin-setup/)—the admin setup this fits into

Source: https://docs.alpacax.com/learn/ai-agents-governance/
