arkheia-mcp: Instructions file for Codex

Arkheia MCP Server — Setup Guide

This file is the single source of truth for installing and configuring the Arkheia MCP Server. If you are an AI agent helping a user install Arkheia, follow these steps exactly.

Prerequisites

• Python 3.10+ — check: python3 --version (or python --version on Windows)
• Git — check: git --version

Step 1: Get an API Key

Option A — Automatic (recommended):

curl -X POST https://arkheia-proxy-production.up.railway.app/v1/provision \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

This returns {"api_key": "ak_live_..."}. Save this key.

Option B — Manual: Visit https://arkheia.ai and sign up. Your key will be emailed.

Step 2: Configure Claude Desktop

Edit your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

First, clone the repo and create a virtual environment (one time only):

git clone https://github.com/arkheiaai/arkheia-mcp.git ~/.arkheia-mcp
cd ~/.arkheia-mcp
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

On Windows, use %USERPROFILE%\.arkheia-mcp instead of ~/.arkheia-mcp.

Then add this to the config file (create it if it doesn't exist):

{
  "mcpServers": {
    "arkheia": {
      "command": "~/.arkheia-mcp/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "~/.arkheia-mcp",
      "env": {
        "PYTHONPATH": "~/.arkheia-mcp",
        "ARKHEIA_API_KEY": "ak_live_YOUR_KEY_HERE"
      }
    }
  }
}

On Windows, replace ~/.arkheia-mcp with the full path, e.g. C:/Users/YourName/.arkheia-mcp.

Replace ak_live_YOUR_KEY_HERE with your actual API key from Step 1.

Step 2 (alt): Configure Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "arkheia": {
      "command": "~/.arkheia-mcp/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "~/.arkheia-mcp",
      "env": {
        "PYTHONPATH": "~/.arkheia-mcp",
        "ARKHEIA_API_KEY": "ak_live_YOUR_KEY_HERE"
      }
    }
  }
}