Companion Hub MCP

Companion Hub exposes a Model Context Protocol server that lets an agent manage the appliance — discover apps, install and control them, read logs, inspect configuration, and proxy calls into the apps themselves.

Find your address first

The path is always /api/mcp. What comes before it — written <hub-url> throughout this section — depends on how you reach the appliance, and 5002 only appears when you are talking to Hub’s published port directly.

The dashboard can hand you the address. Open Settings → MCP and copy the Endpoint value. It is built from the address your browser is using, so open the dashboard the same way your agent will reach the Hub — from http://localhost:5002 it shows a localhost address that no other machine can use. The same tab shows the server status, the protocol versions, the tool count, and the number of connected sessions.

ci-hub.local is the Host name Traefik matches, and it works only where your network resolves it (ci-os-hub.local on an appliance installed before the container was renamed). When you are not sure it resolves, use the IP address and port 5002.

Endpoint

The value injected into apps as HUB_MCP_URL is the complete endpoint — http://ci-hub:5002/api/mcp, already carrying the path. (HUB_URL is the bare origin, http://ci-hub:5002.) Both use an internal Docker hostname that only resolves inside the appliance’s container network — ci-os-hub instead of ci-hub on an appliance installed before the container was renamed — so an app should consume HUB_MCP_URL as-is rather than appending /api/mcp to it. From your own machine, use the appliance’s LAN address or a tunnel origin instead.

Protocol dual-stack

Hub serves two MCP protocol revisions on the same /api/mcp endpoint:

The Hub inspects each inbound POST and routes legacy traffic to the session registry; modern traffic is handled statelessly. Existing clients that send a plain initialize request continue to work unchanged.

How one endpoint serves both, decided per request:

flowchart TD
    P["POST hub-url/api/mcp"] --> I{"Which revision<br/>is the client speaking?"}
    I -->|"2025-11-25 — initialize first,<br/>then Mcp-Session-Id on every call"| L["Session registry<br/>(sessionful, what most agents use today)"]
    I -->|"2026-07-28 — per-request<br/>_meta envelope, no session"| M["Stateless handler<br/>(SDK v2, versionNegotiation auto)"]

Getting a key

From the Hub dashboard, under Settings → Security — or on the appliance host:

cihub api-key create --name "my-client" --capability read

For details, including how to choose a capability, see Get your API keys.

What the tools can do

Hub’s tools are named hub_*. They cover app discovery and lifecycle, app configuration, backups, custom apps, inference backends and models, app-store management, links, Cloudflare and registration status, system information and updates, and app proxying.

Which of them your agent sees depends on your key’s capability, because tools/list is filtered. The counts below are from Hub 0.3.0; a later release can add tools, so treat them as a signal rather than a target:

This replaced an older appliance-wide switch that granted destructive access to every key at once. Capability is now per credential, so one agent having it does not mean all of them do.

Verify the connection

Do not trust a single successful call. Run the handshake and count the tools:

BASE="<hub-url>/api/mcp"
KEY="<hub-key>"
 
# Keep the headers and the body, so you can read the status code and serverInfo.
HDRS=$(mktemp)
curl -s -D "$HDRS" -X POST "$BASE" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"verify","version":"1"}}}'
 
head -1 "$HDRS"                 # HTTP status — 200 is what you want
SID=$(grep -i '^mcp-session-id:' "$HDRS" | tr -d '\r' | awk '{print $2}')
echo "session: $SID"
 
curl -s -X POST "$BASE" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $KEY" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

$Base = '<hub-url>/api/mcp'
$Key  = '<hub-key>'
 
$Headers = @{ Authorization = "Bearer $Key"; Accept = 'application/json, text/event-stream' }
$Init = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"verify","version":"1"}}}'
 
$sid = $null
try {
  $res = Invoke-WebRequest -UseBasicParsing -Uri $Base -Method Post -Headers $Headers -ContentType 'application/json' -Body $Init
  "status: $([int]$res.StatusCode)"
  $res.Content
  $sid = @($res.Headers['mcp-session-id'])[0]
} catch {
  $code = [int]$_.Exception.Response.StatusCode
  if ($code) { "status: $code" } else { "failed: $($_.Exception.Message)" }
}
"session: $sid"
 
if ($sid) { $Headers['mcp-session-id'] = $sid }
$List = '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
try {
  (Invoke-WebRequest -UseBasicParsing -Uri $Base -Method Post -Headers $Headers -ContentType 'application/json' -Body $List).Content
} catch {
  $code = [int]$_.Exception.Response.StatusCode
  if ($code) { "status: $code" } else { "failed: $($_.Exception.Message)" }
}

A successful initialize prints HTTP/1.1 200, returns serverInfo: {name: "ci-hub", ...} in the body, and issues an Mcp-Session-Id header. tools/list should then return a non-empty tools array — 76 tools for a full key, 60 for write, and 33 for read, as of Hub 0.3.0.

If the first call does not return 200, the response body names the cause. Missing Authorization header means Hub received no Authorization header, which is what you get when you send x-api-key. Malformed Authorization header means the header was not Bearer <key>. Invalid API key means the key is unknown, revoked, or lacks the mcp scope. A 429 means the endpoint’s rate limit — 300 requests a minute per client by default — was reached, and a 503 means Hub could not reach its key store, which is an appliance problem rather than a key problem.

Rotating and revoking

Settings → Security lists every key and lets you change a key’s capability or delete it. Raising a capability asks for confirmation; lowering one does not. Settings → MCP shows how many keys are active.

From the CLI, cihub api-key list shows every key with its scopes, capability, and prefix — never the key itself. The CLI has create and list only, so there is no subcommand for changing or revoking; use the dashboard. The admin routes behind the UI (PATCH /api/api-keys/:id to change a capability, DELETE /api/api-keys/:id to revoke) need a signed-in session or an operator credential from the appliance host. The MCP keys minted for clients cannot call them — those are hashed and authenticate the MCP surface only.

Mint a separate key per client so revoking one does not disturb the others.

Installed marketplace MCP servers

Hub also bridges MCP servers you install from the CI Marketplace (apps with "categories": ["mcp", …]). Those apps run as containers on the appliance; Hub connects to them over stdio (docker exec) or HTTP (when the catalog entry pins mcp.url). Your agent reaches their tools through the same /api/mcp endpoint, but not as separate entries in tools/list — it discovers them with hub_list_app_tools and calls them with hub_call_app_tool.

One key, one endpoint, and every bridged server behind it:

flowchart TB
    A["Your agent"] -->|"Authorization: Bearer hub-key"| H["Hub MCP<br/>hub-url/api/mcp"]
    H --> N["Native hub_* tools<br/>filtered by capability"]
    H -->|"hub_list_app_tools<br/>hub_call_app_tool (full key)"| B["Bridge"]
    B -->|"stdio<br/>docker exec"| S["Marketplace MCP app<br/>container must be running"]
    B -->|"HTTP<br/>mcp.url from the catalog"| T["Marketplace MCP app<br/>HTTP endpoint"]
    B -->|"host_docker<br/>ephemeral docker run"| U["Marketplace MCP app<br/>bridged while installed"]

After installing an MCP app from the store:

1. Open the app page — the MCP server card shows bridge status, tool count, and client config.
2. Use hub_list_app_tools (Settings → MCP tool runner, or any MCP client) to discover bridged tools.
3. Call app tools with hub_call_app_tool. hub_list_app_tools returns each name prefixed with the app’s URN, written with _ in place of the colon (<appName>_<storeSlug>__<tool_name>), and hub_call_app_tool accepts either the prefixed or the bare tool name.

Most stdio apps require the app container to be running before bridging. host_docker listings (e.g. github-mcp) spawn an ephemeral docker run on the Hub host instead and bridge when the app is installed, with credentials from app.env.

Install-time configuration comes from form_fields in the marketplace config.json. Hub applies catalog defaults for optional-only MCP apps (for example n8n-mcp with no credentials filled in). The catalog keeps mcp.env in sync with those fields so agent clients see the same keys.

HTTP MCP listings must declare mcp.url in the catalog (internal http://service:port/path or a hosted endpoint). Without it, Hub cannot bridge the server and the app details card shows Not bridgeable.

For config.json fields such as form_fields, see Submitting to the marketplace.