Connect an AI agent with the MCP server

Enclavia ships a Model Context Protocol server so you can manage your enclaves from any MCP-aware AI client — Claude, ChatGPT, Cursor, the OpenAI Codex CLI, or anything else that speaks the spec — using natural language. It's the same surface as the CLI (list enclaves, inspect status and logs, create, stop, destroy), exposed as MCP tools and authenticated against your Enclavia account.

The MCP server is one of two ways to give an agent access. If your agent already runs in a terminal, the CLI with --json plus the agent skill is more token-efficient and exposes the full command surface (including push, secret, upgrade, and reproduce). Reach for the hosted MCP server when you want zero local setup; reach for the CLI skill when the agent has a shell.

The hosted endpoint for the public beta is:

https://mcp.beta.enclavia.io/mcp

It speaks the standard Streamable HTTP transport and authenticates via OAuth 2.1 (PKCE-S256) against api.beta.enclavia.io. Most clients will discover both automatically — paste the URL and follow the consent flow.

Add the connector

Pick the tab for your client. The OAuth flow is identical across all of them: you'll be redirected to api.beta.enclavia.io to authorize the connector against your Enclavia account (the same flow that backs enclavia auth login), then bounced back to your client with the connector linked.

1. In Claude (claude.ai or Claude Desktop), open Settings → Connectors → Add custom connector.
2. Paste https://mcp.beta.enclavia.io/mcp into the connector field.
3. Save. Claude will redirect you to authorize. Approve the consent screen and you'll be bounced back to Claude.
4. Enable the connector in any chat to start using the tools.

If the consent screen logs you in via GitHub or Google first, that's because your browser session at beta.enclavia.io had expired — sign back in, then re-trigger the connector and it will skip straight to consent.

What the agent can do

The connector exposes one tool per CLI verb. Anything the agent calls runs against your account, scoped by the OAuth token issued during the authorization step. Tools currently available:

Tool	Equivalent CLI
enclave_list	enclavia enclave list
enclave_status	enclavia enclave status <id>
enclave_logs	enclavia enclave logs <id>
enclave_create	enclavia enclave create [--instance-type ... --container-port ... --storage-size-bytes ...]
enclave_start	enclavia enclave start <id>
enclave_stop	enclavia enclave stop <id>
enclave_destroy	enclavia enclave destroy <id>
upgrade_chain	enclavia upgrade chain <id>
upgrade_list	enclavia upgrade list <id>
upgrade_status	polls one staged upgrade (enclavia upgrade list <id> shows the same fields)
upgrade_confirm	enclavia upgrade confirm <id> <upgrade-id> (managed custody only)
upgrade_revoke	enclavia upgrade revoke <id> <upgrade-id> (managed custody only)

A useful prompt to verify the connector is wired up:

List my enclaves and tell me which are running.

The agent will call enclave_list and summarise. If you're brand new, ask the agent to create an enclave for you — it will reserve one in your account and tell you the enclavia push command to run next. See Sample apps for ready-to-push images that take you from waiting_for_image to running in a few minutes.

Scope and authentication

• Identity is established via OAuth 2.1 (PKCE-S256) against api.beta.enclavia.io. The MCP server itself never sees your password or upstream identity-provider token — it only receives the API JWT minted by the backend, attached to each tool call as a Authorization: Bearer <token> header on the inbound MCP request.
• Multi-tenant by design. The MCP server holds no per-user secrets. Two different agent sessions authorized by two different users hit the same process and only see their own enclaves.
• Revoking access takes one click: open the dashboard at beta.enclavia.io, find the active session for enclavia-mcp under your sessions list, and revoke it. Subsequent tool calls from that connector will fail with unauthorized and the agent will offer to re-authorize.

Separate from the CLI login

The MCP connector login and enclavia auth login (Authenticate) are two distinct logins against the same Enclavia account. They share the same consent screen at api.beta.enclavia.io, which is what makes them feel like a single flow, but each client (Claude, ChatGPT, your terminal, …) ends up with its own bearer token tied to its own session:

Where the token lives	What it authorizes
Inside your MCP client (Claude, ChatGPT, Cursor, Codex)	Tool calls from the agent: enclave_list, enclave_create, etc.
~/.config/enclavia/credentials.json on your laptop	The enclavia CLI binary, including enclavia push (which the MCP server intentionally doesn't expose).

You can authorize one without the other. Common patterns: drive the management surface from an agent and never install the CLI (you skip push and reproduce, but the rest works); or run the CLI only and skip the MCP connector entirely. To go all the way from "create" to "running" you need both — the agent creates and inspects, the CLI pushes the image that flips the enclave to building.

Limitations

• enclavia push is not exposed as an MCP tool. Pushing requires a Docker daemon and a local image, both of which live on your machine, not in the MCP server. Ask the agent to create the enclave first (it reserves a private repo for it in your namespace); then push to that enclave's id from the CLI to trigger the build.
• The MCP server doesn't proxy traffic into running enclaves. To talk to an enclave's HTTP service you still use the enclavia client library.

See also

• Drive enclavia from a local AI agent (CLI skill) — the lower-overhead alternative for agents that have a shell, with the full CLI surface.