Getting started

arcane-mcp is a single Go binary. Your MCP client either starts it as a child process and talks to it over standard input and output (stdio, the default), or reaches it over the network when it runs with --http (Streamable HTTP). Either way it needs two things: the URL of your Arcane server and a credential.

1. Create an Arcane API key

1. Sign in to Arcane and open Settings → API Keys.
2. Create a key. Its permissions are those of the user who creates it, so the assistant can do exactly what that user can do in Arcane.
3. Copy the key (it starts with arc_). Arcane shows it once.

The same key can be created through the API with POST /api/auth/me/api-keys (the catalog action api_key.my_create does it too, once the server is running with some other credential).

Note

An API key is sent as X-API-Key and does not expire. You can use ARCANE_USERNAME and ARCANE_PASSWORD instead; the server then logs in and refreshes its session by itself. A few account operations that Arcane accepts only from a logged-in session (passkeys, MFA) use the session when both are configured. See Configuration.

2. Install the server

arcane-mcp is one static binary, published through several channels; Installation compares them and has a page for each. The shortest paths, once a release exists:

You have	Run or install
Node.js	npx -y @jmrp.io/arcane-mcp (npm)
uv	uvx arcane-mcp (PyPI)
Homebrew	brew install jmrplens/tap/arcane-mcp (Homebrew)
Windows	winget install --id jmrplens.arcane-mcp -e (winget)
Docker	ghcr.io/jmrplens/arcane-mcp (Docker)
Claude Desktop	the .mcpb extension (Claude Desktop extension)

No release yet

Nothing is published until the first version is tagged, so those commands do not work yet. Until then, build the server from source.

Build from source

arcane-mcp needs Go 1.27.3. With an older Go installed, GOTOOLCHAIN=go1.27.3 fetches the right one.

git clone https://github.com/jmrplens/arcane-mcp.git
cd arcane-mcp
make build            # writes dist/arcane-mcp
./dist/arcane-mcp --version

Without make: CGO_ENABLED=0 go build -trimpath -o dist/arcane-mcp ./cmd/arcane-mcp. The binary has no runtime dependencies; copy it wherever your MCP client can start it. go install builds it without a clone.

3. Add it to your MCP client

Every stdio entry below starts the binary with ARCANE_URL and ARCANE_API_KEY in its environment. Replace /path/to/arcane-mcp with the absolute path of the binary and the URL with your Arcane server’s. With npx, uvx, dnx or Docker, the command and its arguments are on that channel’s install page; the environment stays the same.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude Desktop:

claude_desktop_config.json

{
  "mcpServers": {
    "arcane": {
      "command": "/path/to/arcane-mcp",
      "env": {
        "ARCANE_URL": "https://arcane.example.com",
        "ARCANE_API_KEY": "arc_..."
      }
    }
  }
}

Claude Code

claude mcp add arcane \
  --env ARCANE_URL=https://arcane.example.com \
  --env ARCANE_API_KEY=arc_... \
  -- /path/to/arcane-mcp

Add --scope user to make it available in every project, or --scope project to write it to the repository’s .mcp.json.

VS Code (Copilot)

VS Code reads .vscode/mcp.json (or the mcp.json of your user profile) and keeps servers under servers. An input with "password": true prompts for the key so it never lands in the file:

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "arcane-api-key",
      "description": "Arcane API key",
      "password": true
    }
  ],
  "servers": {
    "arcane": {
      "type": "stdio",
      "command": "/path/to/arcane-mcp",
      "env": {
        "ARCANE_URL": "https://arcane.example.com",
        "ARCANE_API_KEY": "${input:arcane-api-key}"
      }
    }
  }
}

Generic stdio

Any client that starts MCP servers as processes needs the same three things: the command, no arguments (or flags such as --tool-surface meta), and the environment.

{
  "command": "/path/to/arcane-mcp",
  "args": ["--tool-surface", "dynamic"],
  "env": {
    "ARCANE_URL": "https://arcane.example.com",
    "ARCANE_API_KEY": "arc_..."
  }
}

The server also reads a .env file in its working directory, one KEY=value per line, for anything its environment does not set. Logs go to standard error only; standard output carries the protocol.

For every other client (Cursor, Windsurf, Zed, Cline, Continue, LM Studio, Kiro, Gemini CLI, Codex, JetBrains, Goose) and for the Docker image, see Client setup.

Streamable HTTP

Run one server for several clients with --http (or ARCANE_MCP_HTTP_ADDR). It serves MCP at /mcp and a liveness probe at /healthz.

ARCANE_URL=https://arcane.example.com \
ARCANE_MCP_HTTP_TOKEN=change-me \
./dist/arcane-mcp --http :8080

• ARCANE_MCP_HTTP_TOKEN makes every request to /mcp present Authorization: Bearer <token>. Set it whenever the port is reachable by anyone but you.
• :8080 listens on every interface, so without TLS the server warns at startup that it serves plain HTTP to the network. Use --http 127.0.0.1:8080 when only this machine connects, or see Plain HTTP and the hardened mode.
• Each client may send its own Arcane key in the X-Arcane-API-Key header and then acts with that key’s permissions. Without the header the server falls back to ARCANE_API_KEY (or the configured username and password), and refuses the request if none is configured. See Safety.

Claude Code

claude mcp add --transport http arcane http://localhost:8080/mcp \
  --header "Authorization: Bearer change-me" \
  --header "X-Arcane-API-Key: arc_..."

VS Code (Copilot)

.vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "arcane-api-key", "description": "Arcane API key", "password": true }
  ],
  "servers": {
    "arcane": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer change-me",
        "X-Arcane-API-Key": "${input:arcane-api-key}"
      }
    }
  }
}

Generic HTTP

Point the client at http://<host>:8080/mcp with the Streamable HTTP transport and these headers on every request:

Authorization: Bearer change-me
X-Arcane-API-Key: arc_...

Caution

The bearer token and the Arcane keys travel in the request headers. Before exposing the server beyond localhost or a trusted network, put it behind a TLS-terminating reverse proxy or give it a certificate; HTTP deployment has the recipes.

4. Try it

Ask your assistant something like:

• “List the running containers in the local environment.”
• “Which images have updates available?”
• “Show the last 50 log lines of the db container.”
• “Pull nginx:1.27 and redeploy the web project.”

On the default dynamic surface the assistant first calls arcane_find_action to find the action and its parameters, then arcane_execute_action to run it. Destructive actions come back asking for confirmation; see Safety. Most actions take an optional environmentId, which defaults to ARCANE_ENVIRONMENT_ID (0, Arcane’s local Docker environment).