Installation Guide

The Arcanea MCP server works with any client that supports the Model Context Protocol. Pick your tool below.

Node.js 18+npm / npxMCP-compatible client

Claude Code

Add the server

claude mcp add arcanea npx @arcanea/mcp-server

2
Verify the connection
```
claude mcp list
```
You should see arcanea listed with status: connected.

Start using tools

# Inside any Claude Code session:
/mcp arcanea generate_character --element void

Cursor

Open or create .cursor/mcp.json in your project root

{
  "mcpServers": {
    "arcanea": {
      "command": "npx",
      "args": ["@arcanea/mcp-server"]
    }
  }
}

2
Restart Cursor
```
# Cmd+Shift+P -> Reload Window
```
The Arcanea tools will appear in the MCP panel after restart.

Windsurf

1
Open ~/.codeium/windsurf/mcp_config.json
```
{
  "mcpServers": {
    "arcanea": {
      "command": "npx",
      "args": ["@arcanea/mcp-server"]
    }
  }
}
```
The file lives at ~/.codeium/windsurf/mcp_config.json. Create it if it does not exist.
2
Reload Windsurf
```
# Cmd+Shift+P -> Reload Window
```

Cline

Open the Cline MCP settings panel

# In VS Code with Cline installed:
# Click the MCP icon in the Cline sidebar
# Select "Edit MCP Settings"

Add the Arcanea server

{
  "mcpServers": {
    "arcanea": {
      "command": "npx",
      "args": ["@arcanea/mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

3
Save and reconnect
```
# Save the settings file
# Cline will reconnect automatically
```
Use autoApprove to pre-approve specific tools and skip confirmation prompts.

HTTP Mode

Advanced

1
Start the server in HTTP mode
```
npx @arcanea/mcp-server --transport http --port 3100
```
The server will be available at http://localhost:3100/mcp

Or run persistently with pm2

npx pm2 start "npx @arcanea/mcp-server --transport http --port 3100" --name arcanea-mcp

3
Connect from any HTTP MCP client
```
{
  "mcpServers": {
    "arcanea": {
      "url": "http://localhost:3100/mcp"
    }
  }
}
```
HTTP mode is useful for shared team environments or CI pipelines.

Docker

Coming soon

A Docker image for the Arcanea MCP server is in progress. It will support environment-based configuration, health checks, and multi-world isolation. Subscribe to the changelog for release updates.

# Not yet available
docker pull ghcr.io/arcanea-ai/mcp-server:latest

Environment variables

Variable	Required	Description
`ARCANEA_API_KEY`	optional	API key for authenticated requests. Get yours at arcanea.ai/developers.
`ARCANEA_WORLD_ID`	optional	Default world context. Tools that accept worldId will use this if not specified.
`ARCANEA_BASE_URL`	optional	Override the API base URL. Defaults to https://arcanea.ai/api.

Example — passing env vars to npx

ARCANEA_API_KEY=your_key ARCANEA_WORLD_ID=arcanea npx @arcanea/mcp-server

Troubleshooting

Server not appearing in client

Restart the client after editing mcp.json. The file must be valid JSON with no trailing commas.

npx command not found

Ensure Node.js 18+ and npm are installed. Run: node --version && npm --version

Tools call returns 401 Unauthorized

Set the ARCANEA_API_KEY environment variable. Get your key at arcanea.ai/developers.

HTTP mode: connection refused

Check that the server started without errors and the port matches your client config. Default port is 3100.

Still stuck? Open an issue on GitHub or visit the community.