Changelog

This page is for the people who install and run arcane-mcp. It describes each release by what it lets you do and what you may have to change, not commit by commit. The commit-level notes are on each GitHub release.

Unreleased

The first public release has not been tagged yet, and its version number is still to be decided. Everything below is what it will contain. There is no earlier release, so there is nothing to upgrade from and no migration notes.

It targets Arcane v2.17.2 (released 2026-10-31); Arcane v2.16.x is not supported, and v2.17.0 and v2.17.1 are not tested any more: through a direct agent they can cut image pulls and project deployments short on reused connections, which arcane-mcp no longer works around, so upgrade Arcane to v2.17.2, which fixes it (getarcaneapp/arcane#4592). Since v2.17.1, updater.run, with or without resourceIds, also updates the containers that opted out of updates (a label or the excluded-containers setting) and have a pending update, as Arcane now does for every manual run; pass automatic: true to honour those opt-outs as the scheduled auto-update does. The confirmation of such a run says so. With v2.17.2, project.up and project.redeploy take build: true to rebuild the images of services that have a build section before deploying (a GitOps sync’s redeploy now does that by itself), and Arcane answers unknown records and invalid requests with a 4xx instead of a 500, which the usage notes now describe.

Every Arcane capability, on three tool surfaces

461 actions in 52 domains cover every operation in Arcane’s API (442 in v2.17.2) and the routes Arcane serves outside its API description that a person can use, such as the log and stats streams and the container terminal: containers, images, Compose projects, volumes, networks, Swarm, Podman (pods, Kubernetes YAML, quadlets, secrets, auto-update), environments and agents, registries, GitOps, templates, backups, vulnerability scanning, users, roles, settings and diagnostics. The few routes left out (the edge agents’ own tunnel, test-only builds, the browser UI’s telemetry relay) are listed with their reasons, and a check in CI fails when an Arcane operation is neither an action nor on that list. The tool reference lists every action.
Three ways to present them to your client: dynamic (the default: two tools that search the catalog and run an action), meta (one tool per domain) and individual (one tool per action). Every surface reaches every action with the same parameters and the same safety rules. See Tool surfaces.
Every action has a usage note and related actions, checked against Arcane’s source, so the assistant knows where an ID comes from and what to do next.
Live streams become bounded actions: container, project and Swarm service logs, stats, the live event feed and running a command in a container listen for a few seconds and return what arrived. Image pulls and builds and project deployments are followed to the end and summarised. Files can be downloaded and uploaded. See Streams and files.
Readable results: the text of a result is Markdown sized for the model (a table for a list, field lines for an object) and says what it leaves out (an empty list of containers, images, projects, volumes, networks or environments says which filters can leave it empty), while the structured content always carries the complete value. A result ends with a few suggested next steps. Text that comes from Arcane is cleaned of terminal escape sequences and control characters. See Output format.
Errors that point somewhere: arguments are checked before Arcane is called, and a failure says which parameters are accepted (and, when Arcane rejects fields, each one by the argument you passed, with Arcane’s reason), which list action finds a valid ID, or which credential or role to check.
Gateway-safe catalog: every tool, prompt and resource name, title and description the server lists (schemas and output schemas included) is plain ASCII, for MCP gateways that validate a server’s catalog before admitting it; typographic characters in Arcane’s own descriptions are spelled in ASCII.

Safety

Destructive actions need approval. Deletes, prunes, kills, restores, redeploys and changes to a stack definition do nothing without confirm: true. On clients that support MCP elicitation, the server asks you directly instead, showing the action and its arguments (credentials hidden); declining is a clean “nothing was done”. See Confirmation of destructive actions.
Read-only mode (ARCANE_MCP_READ_ONLY) removes every action that changes anything; safe mode (ARCANE_MCP_SAFE_MODE or --safe-mode) keeps them but answers with a preview of the request (method, path, query, body, and whether it is destructive, under a bold NOT EXECUTED line), which names both spellings, so whoever reads it knows to turn off whichever one the server was started with; exclusions (ARCANE_MCP_EXCLUDE_TOOLS) hide chosen actions or whole domains. An exclusion that matches nothing is reported at startup.
A misspelt safety switch stops the server instead of silently leaving it writing, and so does any unreadable number, duration or log level.
An audit record per call (ARCANE_MCP_AUDIT_LOG): which action ran, with what outcome, and how a destructive one was approved, never argument values.
A deadline per action (ARCANE_MCP_ACTION_TIMEOUT, 30 minutes by default) also bounds long pulls, builds and downloads.
Credentials only where Arcane needs them: public routes (login, version, health…) are called without your key.
No dot segment reaches a request path: a path argument that is . or .., or has such a part (a/../b, %2e%2e), is refused before anything is sent, so a reverse proxy that resolves dot segments cannot turn volume.delete into the deletion of the environment. See Security.
See Safety for all of it.

Remote use over HTTP

Streamable HTTP with --http, besides stdio. Each user can bring their own Arcane API key, and each key gets its own server, so everyone acts with their own permissions in Arcane.
Two ways to authenticate: a shared bearer token (ARCANE_MCP_HTTP_TOKEN), or ARCANE_MCP_HTTP_AUTH=apikey, where the bearer token is the user’s own Arcane API key, checked against Arcane. This suits remote connectors that can only set an Authorization header.
Hardened by default: limits on keys, sessions, concurrent requests, body size and JSON nesting (100 levels per message, as on stdio); a session stays bound to the key that opened it; cross-origin and DNS-rebinding protection (ARCANE_MCP_HTTP_ALLOWED_HOSTS, ARCANE_MCP_HTTP_TRUSTED_ORIGINS); a budget of failed authentications per client address (and per IPv6 /48, so a large IPv6 block cannot rotate past it; ARCANE_MCP_HTTP_AUTH_NETWORK_FACTOR sizes or turns off that limit); trusted-proxy settings that cannot work with the listener stop the server at startup; an optional rate limit per key; /healthz and /readyz probes.
Plain HTTP on the network is announced, or refused: a TCP listener other machines can reach without TLS warns at startup, in every authentication mode. ARCANE_MCP_HTTP_ALLOW_PLAINTEXT=true (--http-allow-plaintext) says a proxy in front encrypts the hop and turns the warning into an INFO line, and false is a hardened mode that refuses to start such a listener (TLS, loopback and unix sockets always start). See Plain HTTP and the hardened mode.
Several Arcane instances from one server: list them in ARCANE_URL as name=url pairs and each HTTP request picks one with X-Arcane-URL. The server never contacts a URL you did not list, and never follows a redirect from Arcane to another host.
A warning when Arcane’s version differs from the catalog’s: at startup, on stdio and over HTTP, the server reads each instance’s version in the background (a public route, without your key, never delaying the start) and logs a warning when its major.minor is not the catalog’s, so a 404 or 422 from a moved route is not mistaken for a bug. /readyz?format=json shows catalogVersion and whether each instance matches it (versionMatch), never the exact version; a difference never makes /readyz fail. See Troubleshooting.
Actions an older Arcane does not have are refused with the reason: each action newer than Arcane v2.10.0 records the release that added it (shown as since by find and arcane://tools/{id}). On an instance known to run an older release, a call to it is refused before anything reaches Arcane, naming both releases; on an instance whose version is unknown or a development build, the call goes through and a 404 carries the same sentence as a hint. See Troubleshooting.
Stateless HTTP (ARCANE_MCP_HTTP_STATELESS), the transport of the 2026-07-28 protocol revision, as an option.
A server card (SEP-2127) at /mcp/server-card and /server-card: the server’s identity, its endpoint, protocol revisions and the headers a connection needs, for clients and registries that discover servers before connecting; never a credential or anything about the Arcane behind it. Cached with an ETag, rate-limited per address (ARCANE_MCP_HTTP_DISCOVERY_RATE_LIMIT_RPS, _BURST), on by default, ARCANE_MCP_HTTP_SERVER_CARD=off removes it. See Server card.
A more robust stdio: a malformed line, one over ARCANE_MCP_STDIO_MAX_LINE_BYTES (16 MiB by default) or one nesting JSON more than 100 levels deep is answered with an error and the session goes on, a server started by hand in a terminal says in one line that it is an MCP server and where client setup is explained, and HTTP-only settings given to a stdio server are named in a startup warning instead of being ignored silently; a value of one that cannot be read no longer stops a stdio server, only an HTTP one.
See Configuration.

Resources, prompts and completions

Resources: environments, containers, projects and images as JSON your client can attach to the conversation, four workflow guides (deploying a Compose project, updating images safely, backing up and restoring a volume, diagnosing an unhealthy container), and the action catalog itself. The results of environment.get, container.get and project.get end with a resource_link to the matching resource.
Prompts: seven step-by-step workflows your client offers as slash commands, such as diagnosing a container, updating a project’s images, a security report or cleaning up disk space. They never skip the confirmation of a destructive step.
Completions: clients that support them suggest environments, containers, projects, images, volumes and Swarm services, taken from your Arcane, as you fill a prompt argument or a resource address.
Progress notifications while long operations run, for clients that ask for them.

Icons

The server, every tool, prompt and resource carry the arcane-mcp icon, for clients that show one. ARCANE_MCP_ICONS=off removes them, for a client that refuses them. See Icons.

Output schemas

Experimental and off by default: with ARCANE_MCP_OUTPUT_SCHEMAS=on, the individual surface declares the shape of each action’s result (420 of the 461 actions), derived from Arcane’s own API description and checked against live results. A result that does not fit is never turned into an error. See Output schemas.

Distribution

Each release will publish binaries for Linux, macOS and Windows on amd64 and arm64 (plus one macOS binary for both), archives, an SBOM per binary, and a signed checksum file with build provenance, so you can check what you downloaded.
A signed and attested container image for linux/amd64 and linux/arm64, ghcr.io/jmrplens/arcane-mcp, also on Docker Hub once it is set up there.
A Claude Desktop extension (.mcpb), one per operating system and one for all three, whose settings ask for your Arcane URL and API key (a field marked sensitive, which Claude Desktop treats as a secret) and offer the surface, read-only and safe mode.
Packages that carry the same release binary: npx -y @jmrp.io/arcane-mcp (npm), uvx arcane-mcp (PyPI), dnx arcane-mcp (NuGet, .NET 10), brew install jmrplens/tap/arcane-mcp (Homebrew) and winget install jmrplens.arcane-mcp (winget, once its first version is merged).
An entry in the MCP Registry, io.github.jmrplens/arcane-mcp, pointing at the extensions, the container image and the npm, PyPI and NuGet packages.
Installation has a page per channel. Until the first release, build from source as Getting started explains. Releasing describes how releases are built and how to verify them.

Tested against a real Arcane

A live end-to-end suite runs every action on all three surfaces against real Arcane v2.17.2 instances, a Podman host included: 455 of the 461 actions succeed; the 6 others cannot be exercised there, for the reasons on E2E coverage.
A model evaluation corpus of 94 realistic requests is ready; no real model has been measured with it yet. The use cases page walks through some of them.

How releases are recorded

This page is written by hand, in English and Spanish, and the GitHub release notes are generated.

Here, every change you would notice (a new capability, a new setting, a different default, something that now stops the server at startup, a fix to behaviour you could see) is added under Unreleased in the same change that makes it. When a version is tagged, that section gets the version number and date as its heading (## v0.2.0 (2026-11-20)), and a new empty Unreleased starts above it; the release workflow refuses a tag whose version has no such section in either language. Changes that ask something of you (a setting renamed, a value now refused) go under a Behaviour changes heading at the top of the release’s section.
On GitHub, each release’s notes are generated from the commit messages, grouped into features, fixes, security and documentation, with the assets and how to verify them.

Why both: the generated notes are complete but follow commits, which also cover tests, CI and internal work, and they are in English only. This site is bilingual, and someone deciding whether to upgrade needs a short summary by capability and a clear list of what they must change, which only a person can write well. The two are kept apart so that neither has to compromise.