AI & API access

With API access, Claude (or another AI) works in Vesana for you: it sees what you may see and can change what you may change — never more. Typical requests:

• "The Windows server crashed yesterday — what happened?"
• "Which problems are open right now, and which of them are urgent?"
• "Set up the devices in my homelab."

Everything about it is under Admin → System → AI:

Tab	Content
Provider	Which model the Vesana chat uses (Ollama, Anthropic, OpenAI-compatible)
Access	All AI & API access on the instance, create access for other people
Settings	AI & API access allowed yes/no, maximum lifetime of new access

The switch is on after the update. When switched off, no access works any more and claude.ai cannot connect; the accesses stay stored.

The AI account

Every access runs on an AI account of the person, for example lukas-ai for Lukas. It is created automatically with the first access.

• The audit log shows the AI account as actor ("lukas-ai, via API access Claude, on behalf of lukas"). So it is clear at a glance what the AI did and what a human did.
• The AI account has no rights of its own. With every request it gets its person's current rights. If the person loses a right, the AI loses it too — immediately.
• It cannot sign in: no password, no 2FA, no SSO.
• User management shows it with the label AI. An admin can deactivate it (all access of the person stops) or delete it; role, tenants and password cannot be set there.
• Dashboards the AI creates belong to the person, and the AI sees its person's private dashboards.

Who may use it

• For yourself, anyone with the permission Create API access (api_tokens.create) can create access. The Admin role has it, Operator and Viewer do not; custom roles get it via a checkbox under Roles.
• For another person, you additionally need Edit users (users.edit) or super admin — and only for people who have no more rights anywhere than the issuer. Otherwise you could hand out more through the access than you have yourself.
• The issuer is accountable: an access only lives as long as its issuer may still create access. If the person later gets more rights than the issuer, the access stops.

Creating access

For yourself: Settings → API access → New access. For a person: Admin → System → AI → Access → Access for a person.

First you choose what the access is for:

• claude.ai: you only set mode, tenants and lifetime. There is no key — claude.ai gets its access when connecting, and the approval takes over these rights. You only confirm there.
• Key: for Claude Code, Claude Desktop or your own scripts. Vesana asks for your identity first (passkey, authenticator code or password), because a key is long-lived access.

Setting	Meaning
Mode: Read only	The AI sees everything the person may see and changes nothing. The right choice for questions and analysis.
Mode: Read + change	The AI may change what the person may change. Sensitive actions stay blocked: creating users, changing script code and everything else for which Vesana would ask for the identity again.
Mode: Full	As above, plus the sensitive actions without asking. Only for an AI you trust with that.
Tenants	Without a selection the access applies in all tenants the person sees, including future ones. With a selection it applies only there, and instance-wide actions are blocked, even for a super admin.
Lifetime	Default 90 days. Under Settings a super admin can set a maximum; "never expires" is then no longer possible.

A key (vesana_pat_…) is shown only once. Vesana does not store it, only a fingerprint of it.

Connecting Claude

claude.aiClaude CodeClaude DesktopOther AI / scripts

claude.ai → Settings → Connectors → Add custom connector and enter as address:

https://<your-vesana-address>/api/v1/mcp

claude.ai then opens Vesana. You sign in, see who wants access, and approve. If you set rights under "New access" → claude.ai, they appear there as one line — one click on "Allow access" is enough, "Change" opens the fields. Otherwise you choose mode, tenants and lifetime here. The access then shows up under Settings → API access (robot icon, "connected via …").

A key you created plays no part in this — claude.ai gets its access through the approval alone.

Different rights or reconnecting: in claude.ai choose "Connect" on the Vesana connector again and change the rights during approval. The new access replaces the old one of the same connector; the old one is revoked (shown as "Replaced").

"A connector with this URL already exists": the connector is already in the list under Settings → Connectors, even if its access was revoked. Choose "Connect" there instead of adding it again.

Address: with split containers, use the user portal's address, not the admin portal's — you need to be signed in there for the approval.

Vesana must be reachable from the internet

claude.ai connects from Anthropic's servers, not from your browser. The address must therefore be reachable from the internet over HTTPS with a valid certificate (e.g. Let's Encrypt, see TLS). If Vesana only runs in your own network, see Instance in your own network.

After creating access, Vesana shows the ready-made command:

claude mcp add --transport http vesana https://<your-vesana-address>/api/v1/mcp \
  --header "Authorization: Bearer vesana_pat_…"

In claude_desktop_config.json (needs Node.js):

{
  "mcpServers": {
    "vesana": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-vesana-address>/api/v1/mcp",
               "--header", "Authorization:Bearer vesana_pat_…"]
    }
  }
}

Any AI that speaks MCP uses https://<your-vesana-address>/api/v1/mcp. Everything else talks to the regular REST API with the header Authorization: Bearer vesana_pat_…. The API description (OpenAPI) is at /api/v1/mcp/openapi.

Instance in your own network

What matters is who opens the connection to the MCP server:

Way	Who connects	Instance only in your own network
Claude Code, Claude Desktop with mcp-remote, own scripts	your computer	works if the computer reaches Vesana (LAN, VPN)
claude.ai, connector in the Claude Desktop settings	Anthropic's servers	only via the AI gateway

Certificate with Claude Code and Claude Desktop: both run on Node.js and do not trust the self-signed certificate of a fresh installation. The simplest fix is a valid certificate via Admin → System → Certificate with DNS-01. This also works when Vesana is not reachable from the internet (see TLS). Alternatively, make the instance certificate known to the client with NODE_EXTRA_CA_CERTS=/path/to/vesana.pem.

AI gateway for claude.ai

The AI gateway is a separate port that only opens what the claude.ai servers need: sign-in (OAuth) and the tools (MCP). The web interface, login and the rest of the API stay closed there. Your browser opens the approval page as usual at the address of the web interface in your own network.

1. Switch on Admin → System → AI → Settings → AI gateway for claude.ai (default port 8445).
2. Make the port reachable from the internet, with a valid certificate for the public address:
   • Port forwarding on the firewall to the Vesana server, port 8445. The gateway uses the same certificate as the web interface, so the public address must be on that certificate too (Admin → System → Certificate, several names or a wildcard via DNS validation). If you like, restrict it to the addresses Anthropic publishes.
   • Tunnel (e.g. Cloudflare Tunnel): the tunnel points to https://<vesana-server>:8445, no inbound port needed. The tunnel service provides the public certificate; let it accept the server's self-signed certificate unverified (with Cloudflare noTLSVerify).
3. In claude.ai, enter https://<public-address>/api/v1/mcp as connector, with :8445 when using port forwarding.

BASE_URL in the .env must be the address of the web interface as your browser calls it. Without it, the approval page cannot be opened; the card in the admin area tells you.

The Vesana chat with Vesana data

The built-in AI chat has the same tools. When the source Vesana is switched on next to wiki and web, it queries the data of the instance — with your rights, through your AI account. Above the answer it lists which tools ran.

• On its own, the chat only reads.
• If it wants to change something, it stops and shows the planned change with Run and Cancel. Only after "Run" does exactly this one change happen, then the chat continues. Sensitive actions (users, script code …) the chat never does.
• The audit log shows "via Vesana chat".
• This works with Anthropic and OpenAI-compatible providers. With Ollama it depends on the model: not every local model can use tools. Then the chat answers without Vesana data and says so.

What the AI can do with it

Tool	Purpose
Search	Find hosts, checks, tenants, folders by name
Current problems	What is not OK right now, worst first
Host	One device with all checks and open problems
Host timeline	What happened in a time window: status changes, connection and agent outages, configuration changes, warnings and errors from the logs
Check history	Status changes and value curve
Logs	Search collected log entries (Windows event log, journald, files)
API catalog + API call	Everything the UI can do: create hosts, set up checks, start discovery, change the device view of a device or profile …
Overview	Status, tenants, collectors, active checker, alerting and unmonitored devices in one call
Guide	Vesana's knowledge and procedures, e.g. on building checks or on alerting — the AI loads it itself before it plans something
Check catalog	The built-in check types with their fields

Every call goes through the same permission checks as the UI. The AI finds no way around the person's rights, because there is none.

What the AI does not see: device data Vesana never collected. "Why did the server crash?" is answered best when log collection is enabled on the host. Without it the AI only sees outages and status changes.

Workflows

Workflows are ready-made assignments. They tell the AI in which order to proceed, what to watch for in Vesana and what the result looks like. They run with the rights of the access; the AI proposes changes and only carries them out after your OK.

Workflow	ID	Purpose
Check Design	check-design	Build a new check or improve an existing one following Vesana's best practice, verified on the real device
Monitoring Review	monitoring-review	Find gaps and weak spots: hosts without checks, permanent NO_DATA, missing thresholds, alerting gaps
Coverage Gap Analysis	coverage-gap-analysis	Devices on the network that are not monitored yet, with a profile proposal
Device Onboarding	device-onboarding	Add a device: tenant, folder, profile, access data, execution path
Incident Analysis	incident-analysis	What happened and why, with a timeline and the likely cause
Alerting Review	alerting-review	Does every problem reach the right people, where do unnecessary messages come from
Maintenance Window	maintenance-window	Plan a downtime, dependent devices included
Status Report	status-report	Availability, incidents and open items of a tenant for a period

How to start a workflow:

• claude.ai and Claude Desktop: click + in the input field → Vesana → pick the workflow and fill in the fields.
• Claude Code: /mcp__vesana__monitoring-review (or the respective ID).
• In the conversation: just say it, e.g. "Run a monitoring review for tenant Example". Claude knows the workflows and also suggests them when they fit.
• Vesana chat: an empty chat offers some workflows as quick start.

The list is also shown under Settings → API access.

What an access can never do

• create or manage API access, sign in, change sessions, password or 2FA
• change its own AI account or its person's account through user management
• read passwords, communities or other secrets (they are *** for everyone)
• more than the person, not even in "Full" mode

Tracking and revoking

• Settings → API access lists your access — the ones you created and the ones for you — with AI account, mode, tenants, lifetime and "last used from …". One click revokes it, immediately.
• Admin → System → AI → Access lists all access of the instance with person and issuer (super admins).
• A new access is also recorded in the diagnose log (category sign-in).
• An access stops working automatically when the person's account is deactivated or deleted, when their AI account is deactivated, when an admin resets their password, when the issuer loses the permission, or when AI access is switched off.

Careful

Instructions in device data. An AI reads texts that come from devices: check messages, log lines, host names. Whoever controls a device can put text there that looks like an instruction ("delete all hosts"). Vesana explicitly marks such data as data towards the AI, Claude asks before changing tools, and the Vesana chat never changes anything without your confirmation. The most effective precaution is still: "Read only" for anything that is only meant to ask, and "Full" only when you really need it.

Data at the provider. What an AI queries through access goes to its provider — Anthropic for claude.ai, the one set under "Provider" for the Vesana chat. For customer environments, check beforehand whether that is allowed.