FAQ

Which tool surface should I choose?

Keep the default, dynamic, unless you have a reason not to. It shows the client two tools (arcane_find_action to search the catalog, arcane_execute_action to run an action), costs about 400 tokens of context and works with every client, including those that cap the number of tools.

• Choose meta (52 tools, one per domain, about 16 k tokens) if your model does better with a fixed list it can read up front.
• Choose individual (461 tools, about 111 k tokens) if you want your client to approve or allow tools one by one. It exceeds some clients’ limits (VS Code accepts 128 tools per request), so pair it with ARCANE_MCP_EXCLUDE_TOOLS to trim it.

All three reach every action with the same parameters and the same safety rules; only the shape of the tool list changes. See Tool surfaces and, per client, Client setup.

How do I make sure the assistant cannot change anything?

Use two limits, one in arcane-mcp and one in Arcane:

1. Start the server with ARCANE_MCP_READ_ONLY=true (or --read-only). Every action that changes anything is removed before the client sees the tool list, on every surface; a call that names one anyway is refused with the reason (on the individual surface its tool does not exist). Reads and resources keep working, and so do most prompts, without their steps that change state.
2. Give it an API key of an Arcane user whose role can only read. arcane-mcp acts with exactly the permissions of the key’s user, so this holds even if the server were started without the flag.

If you want the assistant to see the actions that change things but not run them, use safe mode instead (next question). See Read-only mode.

What is the difference between read-only mode and safe mode?

• Read-only (ARCANE_MCP_READ_ONLY) hides every action that changes state. The assistant cannot even find them.
• Safe mode (ARCANE_MCP_SAFE_MODE) keeps them visible, but a call that would change something returns a preview of the request it would have sent (method, path, body) and sends nothing. It is useful for trying prompts against a production Arcane, or for reviewing what an assistant would do before you allow it.

Some checks change Arcane’s stored data even though they look like reads; image_update.check_ref and updater.project_check, for instance, store their results. They count as changes, so read-only mode hides them and safe mode previews them. The tool reference shows each action’s kind.

What does the confirmation of destructive actions do?

An action that deletes or replaces state (deletes, prunes, kills, restores, redeploys, changes to a stack definition) does nothing until it is approved, in one of two ways:

• Your client supports MCP elicitation: the server asks you directly, in the client’s interface, naming the action and what it will send (credentials shown as (hidden)). Accept runs it; decline returns “nothing was done” and the model is told not to retry. If nobody answers within five minutes (ARCANE_MCP_ELICITATION_TIMEOUT), nothing runs.
• Otherwise: the call is refused with a message telling the model to ask you and repeat the call with confirm: true.

Be clear about what this protects against. It stops accidents and keeps you in the loop with a model that follows instructions, but confirm: true is an argument the model writes: a model that sets it without asking you skips the question. If that is not acceptable, add a limit the model cannot write around: per-tool approval in your client (the individual surface marks destructive tools with destructiveHint), safe mode, read-only mode, exclusions, or an Arcane role without the permission. See Confirmation of destructive actions.

Can I use it from another machine, and how do I do it safely?

Yes. Start it with --http 0.0.0.0:8080 (or ARCANE_MCP_HTTP_ADDR) and clients connect to /mcp over Streamable HTTP. Before exposing it beyond a network you trust:

• Require authentication. Either set ARCANE_MCP_HTTP_TOKEN, a shared bearer token every client must send (each user can still bring their own Arcane key in X-Arcane-API-Key), or set ARCANE_MCP_HTTP_AUTH=apikey, where the bearer token is the user’s own Arcane API key, checked against Arcane. The second suits remote connectors and mcp-remote, which can only send an Authorization header. Without either, anyone who can reach the port can use the server; it logs a warning at startup.
• Encrypt. The bearer token and Arcane keys travel in the requests. Terminate TLS in a reverse proxy, or give the server a certificate with ARCANE_MCP_HTTP_TLS_CERT and ARCANE_MCP_HTTP_TLS_KEY. A listener like 0.0.0.0:8080 without TLS warns at startup that it serves plain HTTP to the network: ARCANE_MCP_HTTP_ALLOW_PLAINTEXT=true declares that a proxy encrypts the hop, and false makes the server refuse to start on such an address (see Plain HTTP and the hardened mode).
• Set ARCANE_MCP_HTTP_ALLOWED_HOSTS to the host names clients use, against DNS rebinding.
• Behind a reverse proxy, set ARCANE_MCP_HTTP_TRUSTED_PROXIES and ARCANE_MCP_HTTP_TRUSTED_PROXY_HEADER. Otherwise every client shares the proxy’s address and one budget of failed authentications (10 a minute by default), and one client’s mistakes can lock out the others for a minute.
• Optionally, limit each key’s request rate with ARCANE_MCP_HTTP_RATE_LIMIT_RPS.

Read-only mode, safe mode and exclusions are set where the server runs and apply to every user of it. See HTTP deployment for Compose and reverse-proxy recipes, and HTTP mode and HTTP authentication for the settings.

Can one server manage several Arcane instances?

Yes, over HTTP. List them as ARCANE_URL=home=https://nas.lan:3552,lab=https://lab.example.com; each request names its instance in the X-Arcane-URL header, and the server refuses any instance you did not list. API keys belong to one Arcane, so ARCANE_API_KEY then takes one key per instance (home=arc_...,lab=arc_...), or users bring their own.

Over stdio a server serves one instance: with several listed, ARCANE_MCP_INSTANCE picks it. To use two instances from a desktop client, add two entries, one per instance.

Several environments (Docker hosts) of one Arcane need nothing of this: every action takes an environmentId, which defaults to ARCANE_ENVIRONMENT_ID (0, Arcane’s local Docker), and environment.list gives the IDs. See Several instances.

Why are some actions not tested?

The live end-to-end suite runs every action on all three surfaces against real Arcane v2.17.2 instances, and 455 of the 461 succeed. The other 6 cannot succeed in that test setup:

• Setups the test estate cannot have: image.patch needs a Docker daemon on the containerd image store; backup.restore, system.upgrade and system.update_all need Arcane to run inside the Docker daemon it manages and, for the last two, to replace its own container, which would end the test run; system.update_all_status only answers after system.update_all has run.
• A deprecated compatibility route: job.resolve_run only succeeds for runs of agents older than v2.16.

They stay in the catalog because every Arcane capability is offered, and on a setup where Arcane can do the work they behave like any other action. E2E coverage quotes the full reason for each.

Does arcane-mcp send telemetry?

No. It has no telemetry, analytics, crash reporting or update check, stores nothing on disk, and talks only to your MCP client and the Arcane servers you configure. Logs go to standard error and never contain argument values. See Privacy.

Which Arcane versions are supported?

The catalog is generated from the API description of Arcane v2.17.2, and every test runs against v2.17.2, so that is the version it supports. Arcane v2.16.x is not supported: the catalog targets one release.

At startup arcane-mcp reads each Arcane instance’s version in the background and logs a warning when its major.minor differs from the catalog’s; it never refuses to run (see Troubleshooting). Against another version, an action Arcane still serves the same way works, one whose route or fields changed fails with Arcane’s own error, and anything Arcane added later is missing until the catalog is regenerated from that release. On an older Arcane, an action that release does not have yet is refused with the release it needs (podman.status exists since Arcane v2.17.0) instead of failing with a bare 404 (see An action needs a newer Arcane). Each arcane-mcp release names the Arcane version it targets in the changelog.

Does it need an administrator’s API key?

No. Give it a key of a user with the smallest role that covers what you want the assistant to do. arcane-mcp never has more rights than that user: Arcane checks the key’s permissions on every request, and a refusal comes back with a hint about the role assignment involved. A few account operations (passkeys, multi-factor authentication, creating your own API keys) are accepted by Arcane only from a logged-in session; they need ARCANE_USERNAME and ARCANE_PASSWORD as well.

Is arcane-mcp made by the Arcane team?

No. It is an independent open-source project that uses Arcane’s public API. Report problems with arcane-mcp in its repository, and problems with Arcane itself to Arcane.