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.

Endpoint

The value injected into apps as HUB_MCP_URL is the complete endpoint — http://ci-os-hub:5002/api/mcp, already carrying the path. (HUB_URL is the bare origin, http://ci-os-hub:5002.) Both use an internal Docker hostname that only resolves inside the appliance’s container network, 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.

Getting a key

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

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

Full detail, including how to choose a capability, is on Get Your API Keys.

What the tools can do

Hub’s tools are named hub_* and cover app discovery, lifecycle, configuration, backups, system information, and app proxying.

Which of them your agent sees depends on your key’s capability, because tools/list is filtered:

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 — a full key sees the whole surface, a read key sees fewer by design.

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.

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. The admin routes behind the UI (PATCH /api/api-keys/:id to change a capability, DELETE /api/api-keys/:id to revoke) are reachable from a script: Hub’s auth middleware accepts the operator token (ciHubApiKey) as a bearer. 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) and re-exposes their tools through the same /api/mcp endpoint alongside the native hub_* tools.

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 — names are prefixed <appUrn>__<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.

See CI-Marketplace MCP catalog architecture  for author guidelines (form_fields ↔ mcp.env, compose defaults, field types).