AI & MCP Integration

CitadelHosts exposes a Model Context Protocol (MCP) server so AI assistants such as Claude Desktop, ChatGPT, and coding agents can manage your account directly: list territories, check app status, read logs, deploy apps, and more.

1. Create an API key

Sign in and open Dashboard → Profile.
In the API Keys section, give the key a name (e.g. Claude Desktop).
Pick a permission level:
- Read only — the assistant can view territories, apps, logs, backups, volumes, jobs, and billing status, but cannot change anything.
- Read + Write — the assistant can additionally create, start, stop, and delete resources, and manage backups. This can spend credits, so grant it deliberately.
Copy the displayed key (it starts with cht_). It is shown once; only a hash is stored.

Revoke a key at any time from the same page. Each account can hold up to 10 keys.

2. Connect your AI client

The MCP endpoint is:

https://citadelhosts.com/api/mcp

Configure it with your API key as a bearer token.

=== "Claude Desktop"

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "citadel-hosts": {
      "command": "mcp-remote",
      "args": [
        "https://citadelhosts.com/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_cht_KEY"
      ]
    }
  }
}
```

(Requires [Node.js](https://nodejs.org) for `mcp-remote`.)

=== "HTTP-capable clients"

POST JSON-RPC directly to the endpoint:

```bash
curl -X POST https://citadelhosts.com/api/mcp \
  -H "Authorization: Bearer YOUR_cht_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-03-26",
                 "capabilities":{},
                 "clientInfo":{"name":"my-client","version":"1.0"}}}'
```

3. Available tools

Read-only keys see tools such as:

Tool	Description
`list_territories`	Territories with limits, status, and pricing
`list_apps`	All managed applications
`get_app_details`	Containers, ports, volumes, and env for an app
`get_app_logs`	Captures a few seconds of container logs
`list_backups` / `list_backup_tasks`	Backup history and schedules
`list_storage_volumes`	Standalone volumes with usage
`get_billing_balance`	Credit wallet balance
`list_jobs`	Queued/active/failed background jobs
`list_available_apps`	Application catalog
`list_custom_images`	Images pushed to your Smart Image Registry
`get_app_link`	The public URL a deployed app is reachable at

Read + write keys additionally get tools to create/delete territories, deploy apps, start/stop/kill containers, schedule and restore backups, manage storage volumes, and ship custom applications (create_custom_app, get_registry_credentials).

Custom applications from an AI agent

The MCP server covers the full custom-app pipeline that otherwise requires the dashboard plus a terminal:

get_registry_credentials — returns the registry host (registry.citadelhosts.com), your username, and the password: your own cht_ API token. Read + write keys can be used directly as the registry password with docker/podman/skopeo login, so an agent can build and push images without ever seeing your account password.
The agent tags and pushes images as registry.citadelhosts.com/<app-name>:<tag>. The registry automatically scopes every repository to your account, so no namespace is needed in the path.
list_custom_images — verifies the pushes landed.
create_custom_app — registers the application definition: containers, images (your pushed repo:tag for custom images, or fully-qualified public images such as docker.io/library/postgres:16), published ports, volumes, and env vars.
create_app — deploys it onto a territory using the definition id returned in step 4.
get_app_link — hands back the public URL to share with you.

Registry logins with an API token mint a short-lived, scope-limited token (2 hours) instead of a full web session; pushing again after expiry is just another get_registry_credentials call. Read-only keys cannot log in to the registry at all.

If a key lacks the scope, the write tool is not even advertised to the model — and the underlying API rejects the call with insufficient_scope regardless, so scope enforcement is enforced server-side, not just by tool visibility.

Security notes

Keys are stored as SHA-256 lookup digests plus argon2 hashes; a leaked database dump cannot reveal usable keys.
API keys of any scope cannot create, list, or revoke keys, and cannot change the account password; key management and password changes require a signed-in web dashboard session.
MCP traffic is rate-limited per user. Requests beyond the limit receive a Retry-After header.
Revoking a key takes effect immediately.