Appearance
Tools & Resources
The complete reference for what an agent can call over the MCP server. Every tool declares the scope it requires; a token without that scope gets a gateway 403 returned as a tool error.
Tools
tools/list returns 13 tools.
Introspection
whoami
Scope: none — always available. Returns this token's identity, role, and the exact scopes it holds. Call it first: each tool below names the scope it needs, so whoami tells an agent which ones it can actually use. No arguments.
Inventory
list_hosts
Scope: inventory:read. Lists the hosts SeyalRun can broker sessions to. No arguments.
get_host
Scope: inventory:read. One host by id.
| Argument | Type | |
|---|---|---|
host_id | string | required |
list_zones
Scope: inventory:read. Network zones — the gateway / ProxyJump topology. See Zones & gateways. No arguments.
create_host
Scope: inventory:write. Registers a new host.
| Argument | Type | |
|---|---|---|
name | string | required |
ip | string | required |
group_ids | string[] | required — at least one asset group |
port | integer | default 22 |
zone_id | string | optional |
Registering a host does not grant access to it. Whether anyone — human or agent — may open a session still depends on an authorization and a credential.
Automation
list_automation_templates
Scope: automation:read. The job templates (Ansible playbooks / bash scripts) available to run. No arguments.
list_job_runs
Scope: automation:read. Recent job runs and their status. No arguments.
run_automation
Scope: automation:run. Runs an allowlisted job template against hosts.
| Argument | Type | |
|---|---|---|
template_id | string | required |
host_ids | string[] | optional — defaults to the template's own targets |
extra_vars | object | optional |
This is the agent's safe "change something on a host" primitive. Only templates an admin authored are runnable, parameters are filtered server-side, and the run appears in Recent Runs with full output like any other.
Observability
query_audit
Scope: audit:read. Queries the tamper-evident audit log.
| Argument | Type | |
|---|---|---|
limit | integer | default 50 |
get_metrics
Scope: metrics:read. The platform metrics dashboard — sessions, jobs, host health. No arguments.
list_sessions
Scope: sessions:read. Lists recorded SSH sessions. No arguments.
list_notifications
Scope: notifications:read. Lists notifications / alerts.
| Argument | Type | |
|---|---|---|
limit | integer | default 50 |
ack_notification
Scope: notifications:ack. Acknowledges a notification.
| Argument | Type | |
|---|---|---|
notification_id | string | required |
Resources
resources/list returns read-only context an agent can pull by URI. Each is backed by the same scope check as the equivalent tool — a resource the token can't read comes back as a JSON-RPC error, not silently empty.
| URI | Scope | Contents |
|---|---|---|
seyalrun://inventory/hosts | inventory:read | All hosts |
seyalrun://inventory/zones | inventory:read | Zones and gateway topology |
seyalrun://automation/templates | automation:read | Available job templates |
seyalrun://audit/recent | audit:read | Most recent audit entries |
seyalrun://metrics/dashboard | metrics:read | Platform metrics |
All resources are application/json.
Tools and resources overlap on purpose: resources are for an agent that wants standing context attached to its conversation, tools for one that wants to ask a question at a specific moment.
What is deliberately absent
There is no tool that executes an arbitrary command on a host. Interactive SSH stays a human surface, where a live operator is attached to supervision, recording and command filtering. The agent path to changing a host is run_automation against a template an admin approved.
If an agent needs a new capability, the answer is to author a job template for it — which is reviewable, diffable, and revocable — rather than to hand the agent a shell.