MCP connections

Stackarr's MCP server is the chat control plane for your homelab. It offers typed actions backed by Stackarr and the APIs of the apps you enabled. It does not expose a generic shell or unrestricted Docker command tool.

Choose authority

The profile is set when the client starts the MCP process. Agents cannot promote themselves.

Generate your connection

Ask the running Stackarr container for a copy-ready connection kit:

docker exec app /app/bin/stackarr mcp config codex --profile admin

Replace codex with claude, lmstudio, chatgpt, hermes, openclaw, or generic. The same generator powers Stackarr's chat tool, authenticated API, and optional dashboard, so every integration receives the same Docker command, authority rules, and app filtering.

Codex

Generate and run the Codex command:

docker exec app /app/bin/stackarr mcp config codex --profile manage

Use admin instead of manage during first-time setup.

Claude and other MCP clients

Generate the mcpServers entry and add it to the client's local configuration:

docker exec app /app/bin/stackarr mcp config claude --profile manage

The generated entry runs docker exec -i on the Docker host and starts /app/bin/stackarr mcp serve inside the private Stackarr container.

LM Studio

Generate the LM Studio entry:

docker exec app /app/bin/stackarr mcp config lmstudio --profile observe

In Program → Install → Edit mcp.json, add the generated server. LM Studio follows mcp.json notation and warns that excessive MCP tools can overwhelm smaller local models. Stackarr already filters uninstalled apps; narrow the groups further when needed:

docker exec app /app/bin/stackarr mcp config lmstudio \
  --profile manage \
  --groups stack,services,arr,downloads,seerr,health

LM Studio's official guide is Use MCP Servers. If the active LM Studio version does not declare MCP form elicitation, Stackarr safely rejects destructive calls. Use observe for read-only access or deliberately select unrestricted if full autonomous control is intended.

ChatGPT without exposing your homelab

ChatGPT is hosted, so it cannot start docker exec on your machine. Stackarr generates an OpenAI Secure MCP Tunnel configuration instead:

docker exec app /app/bin/stackarr mcp config chatgpt \
  --profile manage \
  --tunnel-id tunnel_your_tunnel_id

The generated steps keep Stackarr private:

1. Create an MCP tunnel in OpenAI Platform and associate it with the intended ChatGPT workspace.
2. Run tunnel-client on the Docker host. It opens an outbound HTTPS connection and forwards requests to Stackarr's local stdio server.
3. In ChatGPT developer mode, create a plugin, choose Tunnel, and select the Stackarr tunnel.

No inbound homelab port or public Stackarr MCP endpoint is required. Tunnel and ChatGPT developer-mode availability depends on the user's OpenAI account and workspace permissions. The OpenAI runtime API key stays on the Docker host and must never be pasted into Stackarr or chat.

Authenticated remote MCP

For clients that need an HTTP URL, an admin or unrestricted chat can create a named connection policy. Each policy has its own profile, optional tool groups, revocable bearer token, last-used time, and activity identity. Stackarr shows the token once and stores only its SHA-256 hash.

Enable Authenticated Remote MCP in Stackarr settings and connect the client to:

https://your-private-stackarr-host/mcp

Send the generated token as Authorization: Bearer …. The endpoint is disabled by default, accepts stateless MCP POST requests only, rejects browser origins unless explicitly allowed, and applies the policy before advertising tools. Put TLS and private-network access in front of it. Prefer the OpenAI Secure MCP Tunnel for ChatGPT when available.

Do not publish /mcp directly to the public internet. A token is administrator-issued homelab access, not an OAuth login flow.

How the action catalog stays focused

• Before setup, Stackarr advertises only core setup, connection, status, service, and health actions.
• After setup, it adds actions for the apps you selected.
• Disabled apps do not contribute tools.
• STACKARR_MCP_GROUPS or --groups can narrow the list further for small models or focused agents.
• Reconnect the MCP client after enabling or disabling apps.
• stackarr_get_mcp_connection_kit can generate another client's configuration directly from an existing chat.

Available groups are stack, services, apps, automations, connections, containers, arr, releases, downloads, plex, seerr, backups, and health. The compact apps group routes named operations to enabled Jellyfin, Immich, RomM, Maintainerr, Tracearr, and BookOrbit APIs without exposing an arbitrary HTTP request tool. automations contains saved multi-step routines built from those same allowlisted operations. connections is admin-only and manages revocable remote policies.

Approval behavior

manage and admin request approval for destructive actions through the chat client's MCP prompt. A client without approval-prompt support cannot run those actions. unrestricted is the explicit opt-in for users who want complete autonomy.

App credentials stay on Stackarr's authenticated settings surfaces and are never requested through an MCP approval form. An admin can deliberately create or rotate a remote connection token after a destructive-action approval; that token is returned once.

For Hermes and OpenClaw, continue to Agent plugins.