Puesta en marcha

arcane-mcp es un único binario de Go. Tu cliente MCP lo arranca como proceso hijo y se comunica con él por la entrada y la salida estándar (stdio, el modo predeterminado), o bien lo alcanza por red cuando se ejecuta con --http (Streamable HTTP). En ambos casos necesita dos cosas: la URL de tu servidor Arcane y una credencial.

1. Crea una clave de API en Arcane

1. Inicia sesión en Arcane y abre Settings → API Keys.
2. Crea una clave. Sus permisos son los del usuario que la crea, así que el asistente podrá hacer exactamente lo que ese usuario puede hacer en Arcane.
3. Copia la clave (empieza por arc_). Arcane solo la muestra una vez.

La misma clave puede crearse por la API con POST /api/auth/me/api-keys (también lo hace la acción del catálogo api_key.my_create, una vez que el servidor funciona con otra credencial).

Nota

La clave de API se envía en la cabecera X-API-Key y no caduca. En su lugar puedes usar ARCANE_USERNAME y ARCANE_PASSWORD: el servidor inicia sesión y renueva la sesión por su cuenta. Las pocas operaciones de cuenta que Arcane solo acepta desde una sesión iniciada (passkeys, MFA) usan la sesión cuando ambas credenciales están configuradas. Consulta Configuración.

2. Instala el servidor

arcane-mcp es un único binario estático que se publica por varios canales; Instalación los compara y tiene una página para cada uno. Los caminos más cortos, cuando haya una versión publicada:

Si tienes	Ejecuta o instala
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	la extensión .mcpb (Extensión de Claude Desktop)

Aún no hay ninguna versión

No se publica nada hasta que se etiquete la primera versión, así que esas órdenes todavía no funcionan. Mientras tanto, compila el servidor desde el código fuente.

Compilar desde el código fuente

arcane-mcp necesita Go 1.27.3. Si tienes instalada una versión anterior, GOTOOLCHAIN=go1.27.3 descarga la adecuada.

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

Sin make: CGO_ENABLED=0 go build -trimpath -o dist/arcane-mcp ./cmd/arcane-mcp. El binario no tiene dependencias en tiempo de ejecución; cópialo donde tu cliente MCP pueda arrancarlo. go install lo compila sin clonar el repositorio.

3. Añádelo a tu cliente MCP

Todas las entradas stdio de abajo arrancan el binario con ARCANE_URL y ARCANE_API_KEY en su entorno. Sustituye /path/to/arcane-mcp por la ruta absoluta del binario y la URL por la de tu servidor Arcane. Con npx, uvx, dnx o Docker, la orden y sus argumentos están en la página de instalación de ese canal; el entorno es el mismo.

Claude Desktop

Edita claude_desktop_config.json (Settings → Developer → Edit Config) y reinicia 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

Añade --scope user para tenerlo disponible en todos los proyectos, o --scope project para escribirlo en el .mcp.json del repositorio.

VS Code (Copilot)

VS Code lee .vscode/mcp.json (o el mcp.json de tu perfil de usuario) y guarda los servidores bajo servers. Una entrada de inputs con "password": true pide la clave al usarla, de modo que nunca acaba escrita en el fichero:

.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}"
      }
    }
  }
}

Stdio genérico

Cualquier cliente que arranque servidores MCP como procesos necesita lo mismo: el comando, sin argumentos (o con opciones como --tool-surface meta), y el entorno.

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

El servidor también lee un fichero .env en su directorio de trabajo, con un CLAVE=valor por línea, para lo que su entorno no defina. Los logs van solo a la salida de error; la salida estándar transporta el protocolo.

Para el resto de clientes (Cursor, Windsurf, Zed, Cline, Continue, LM Studio, Kiro, Gemini CLI, Codex, JetBrains, Goose) y para la imagen Docker, consulta Configuración de clientes.

Streamable HTTP

Con --http (o ARCANE_MCP_HTTP_ADDR) un único servidor atiende a varios clientes. Sirve MCP en /mcp y una sonda de disponibilidad en /healthz.

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

• ARCANE_MCP_HTTP_TOKEN obliga a que cada petición a /mcp presente Authorization: Bearer <token>. Defínelo siempre que el puerto sea accesible para alguien más que tú.
• :8080 escucha en todas las interfaces, así que sin TLS el servidor avisa al arrancar de que sirve HTTP sin cifrar a la red. Usa --http 127.0.0.1:8080 cuando solo se conecta esta máquina, o consulta HTTP sin cifrar y el modo endurecido.
• Cada cliente puede enviar su propia clave de Arcane en la cabecera X-Arcane-API-Key y actúa entonces con los permisos de esa clave. Sin la cabecera, el servidor recurre a ARCANE_API_KEY (o al usuario y la contraseña configurados) y rechaza la petición si no hay ninguno. Consulta Seguridad.

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}"
      }
    }
  }
}

HTTP genérico

Apunta el cliente a http://<host>:8080/mcp con el transporte Streamable HTTP y estas cabeceras en cada petición:

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

Precaución

El token bearer y las claves de Arcane viajan en las cabeceras de las peticiones. Antes de exponer el servidor más allá de localhost o de una red de confianza, ponlo detrás de un proxy inverso que termine TLS o dale un certificado; Despliegue HTTP tiene las recetas.

4. Pruébalo

Pide a tu asistente algo como:

• «Lista los contenedores en ejecución del entorno local.»
• «¿Qué imágenes tienen actualizaciones disponibles?»
• «Enséñame las últimas 50 líneas de log del contenedor db.»
• «Descarga nginx:1.27 y vuelve a desplegar el proyecto web.»

En la superficie dinámica, la predeterminada, el asistente llama primero a arcane_find_action para encontrar la acción y sus parámetros, y después a arcane_execute_action para ejecutarla. Las acciones destructivas vuelven pidiendo confirmación; consulta Seguridad. La mayoría de las acciones admiten un environmentId opcional, que por defecto es ARCANE_ENVIRONMENT_ID (0, el entorno Docker local de Arcane).