AI agent integration

Connecting AI coding assistants (Claude Code, Cursor, Antigravity) via Model Context Protocol (MCP).

Guide#guide #mcp #agents #automation #llm Download Markdown

exocomp serves an embedded Model Context Protocol (MCP) server over HTTP at POST /mcp on its LAN listener (Decision 0009 and Decision 0014).

This allows developer assistants (such as Claude Code, Cursor, Antigravity, and Cline) to query homelab state, inspect job outputs, review OpenTofu plans, and queue operational playbooks under strict governance.

Generating an agent token

Mint a scoped bearer token for your agent:

exocomp token new agent-readonly --scope readonly

# Or with operator write permissions:
exocomp token new agent-operator --scope operator

Tokens respect three granular scopes (Decision 0009):

readonly: Read-only queries over jobs, workspaces, drift, checks, netgroups, approvals, sources, schedules, rules, and events.
operator: All read tools, plus workspace_plan, workspace_apply, and check/netgroup management.
approve: All read tools, plus approve_job and reject_job.

Connecting an agent

Claude Code / Antigravity / Cursor MCP configuration

Add exocomp to your MCP client configuration (e.g. claude_desktop_config.json or .gemini/settings.json):

{
  "mcpServers": {
    "exocomp": {
      "url": "https://<host>:<port>/mcp",
      "headers": {
        "Authorization": "Bearer exo_..."
      }
    }
  }
}

Available agent tools

The MCP surface exposes structured tools designed for machine comprehension (see The MCP surface for full catalog and schema):

Tool	Purpose
`list_jobs`, `get_job`	List jobs and inspect job state and exit codes
`get_job_events`	Read execution append-only, redacted event log stream
`list_workspaces`, `get_workspace`	Inspect configured OpenTofu workspaces
`get_drift`	Inspect cached workspace drift and pending plan changes
`workspace_plan`	Enqueue an OpenTofu plan for a workspace
`workspace_apply`	Apply a workspace or sealed plan artifact
`list_checks`, `get_check`, `probe_check`	Inspect probe checks or run live network probes
`list_approvals`, `approve_job`, `reject_job`	Inspect and settle pending human-in-the-loop approvals

(Note: Ansible playbook runs are initiated via POST /api/v1/playbooks/run or the CLI rather than MCP, ensuring inventory and path resolvers remain strictly pinned).

Security guarantees for agents

All execution passes through the queue: An agent cannot bypass the scheduler or execute arbitrary host shell commands.
Secrets never travel across MCP: Secret values are completely stripped and replaced with [redacted · secret].
Approval boundaries: If an operation is marked as requiring approval, the MCP tool returns a status of pending_approval with the approval ID; the agent cannot self-approve without explicit approve scope.