The MCP server: let an AI assistant drive your box¶

MCP (Model Context Protocol) is an open standard that lets an AI assistant call a defined set of tools against a real system instead of just talking about it. eosctl-mcp is Eight.ly OS's MCP server: it exposes the box's API as MCP tools so an assistant you already use — Claude Desktop, Claude Code, or any other MCP-capable client — can read and manage the box directly.

It's built from the same generator and the same API spec as eosctl, so it exposes the same surface the command line tool does and cannot drift from the live API.

What it exposes¶

eosctl-mcp registers 715 tools. Most of them — 696 — map one-to-one onto API operations, one tool per endpoint, grouped by subsystem (storage_*, vm_*, nova_*, backup_*, and so on across 69 groups). The rest are a mix: two general-purpose tools that aren't API calls at all — sql (read-only queries against eosctl's local synced data) and context (a single call that hands the assistant an orientation to the whole API before it starts working) — plus a handful of tools that shell out to the underlying eosctl command for operations that don't map to a single endpoint (bare group commands like backup or vm, and the workflow commands that chain several API calls together).

Running it¶

By default it speaks MCP over stdio — the mode an assistant launches as a subprocess and talks to over stdin/stdout:

eosctl-mcp

It can also serve streamable HTTP instead, for a hosted or remote setup:

eosctl-mcp --transport http --addr :7777

(or set PP_MCP_TRANSPORT=http instead of the flag). It reads its API credential and base URL the same way eosctl does — see Pointing it at a box and signing in: EOS_BEARER_AUTH and EOS_BASE_URL environment variables, or ~/.config/eosctl/config.toml.

Connecting it to an assistant¶

Claude Code:

claude mcp add eosctl-mcp -- eosctl-mcp

Claude Desktop: add it to claude_desktop_config.json:

{
  "mcpServers": {
    "eos": {
      "command": "eosctl-mcp",
      "env": {
        "EOS_BEARER_AUTH": "eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Any other MCP-capable client works the same way: run eosctl-mcp as a stdio subprocess (or point it at the HTTP endpoint) with EOS_BEARER_AUTH set.

It needs an API key — give it the least access that does the job¶

eosctl-mcp authenticates exactly like eosctl: an eos_... API key created from the dashboard's Settings > Security > API Keys screen (see API Keys). Whatever that key can do, the assistant can do — there's no separate MCP-only permission level, and a key created today carries no scope of its own: it inherits the role of the account that created it (admin, operator, or viewer).

That means the only lever you have today is which account you create the key from. If you want an assistant that can read status and logs but shouldn't be able to touch storage or delete a VM, create the key from an operator or viewer account rather than an admin account — don't hand an assistant an admin key just because that's the account you happened to be signed in as. Revoke the key from the same screen the moment you're done with it.

How this differs from Nova¶

Both are Eight.ly's AI features, but they're not the same thing:

• Nova runs on the box itself. It needs no API key — it's already inside the system it's managing, with its own local model, tool router, and talker. See Nova AI Assistant.
• The MCP server is for an assistant you already use somewhere else — on your laptop, in your editor, in Claude Desktop — reaching into the box from outside. It needs a key because, unlike Nova, it isn't already inside the system: it's a normal API client.

Use Nova when you want to ask the box itself a question. Use eosctl-mcp when you want your own assistant to be able to act on the box as part of a larger workflow.