# Aitherium MCP — Full Documentation

> Aitherium exposes a fleet of 29 specialized AI agent personas as MCP tools. Any MCP-compatible client (Claude Code, Cursor, Windsurf, VS Code + Copilot, custom agents) can connect and get deep reasoning, multi-perspective review, persistent knowledge graphs, long-horizon project orchestration, and fully autonomous goal execution — all tenant-isolated and token-metered.

## Architecture

```
Your MCP Client
    |
    | HTTPS (Streamable HTTP / SSE)
    v
mcp.aitherium.com ──> MCPGateway:8182
    |                     |
    | Auth (ACTA)         | Tool dispatch
    v                     v
Token Billing        Genesis:8001 (Orchestrator)
                         |
              ┌──────────┼──────────┐
              v          v          v
         AgentForge   ChatEngine  Expeditions
              |          |          |
              v          v          v
         29 Agent    LLM Gateway  Dark Factory
         Personas   (local/cloud)  (autonomous)
```

All processing happens on Aitherium infrastructure. Your data is tenant-isolated — zero cross-tenant leakage. No artifacts are stored unless you explicitly use Tier 2 memory tools.

## Registration and Authentication

### Step 1: Get an API Key

```bash
curl -X POST https://gateway.aitherium.com/v1/billing/register \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com"}'
```

Response:
```json
{
  "user_id": "user_a1b2c3d4e5f6g7h8",
  "api_key": "aither_sk_live_abc123def456...",
  "balance": 2500,
  "plan": "explorer"
}
```

Save your `api_key` — it starts with `aither_sk_live_` and is your Bearer token for all API calls.

### Step 2: Configure Your MCP Client

#### Claude Code (~/.claude.json or project .mcp.json)

```json
{
  "mcpServers": {
    "aitherium": {
      "type": "streamable-http",
      "url": "https://mcp.aitherium.com/mcp",
      "headers": {
        "Authorization": "Bearer aither_sk_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

#### Cursor (Settings > MCP)

Add server:
- Name: `aitherium`
- URL: `https://mcp.aitherium.com/mcp`
- Auth: Bearer token `aither_sk_live_YOUR_KEY_HERE`

#### Windsurf (Settings > MCP Servers)

```json
{
  "aitherium": {
    "serverUrl": "https://mcp.aitherium.com/mcp",
    "headers": {
      "Authorization": "Bearer aither_sk_live_YOUR_KEY_HERE"
    }
  }
}
```

#### Any MCP Client

- Server URL: `https://mcp.aitherium.com/mcp`
- Transport: Streamable HTTP (with SSE fallback)
- Auth header: `Authorization: Bearer aither_sk_live_YOUR_KEY_HERE`

### Step 3: Verify Connection

Once connected, your MCP client will list available tools. On the free tier you get: `think`, `analyze`, `explain`, `debug` plus code search and memory tools.

## Tool Reference

### Tier 1 — Stateless Analysis

These tools process your input and return analysis. Nothing is stored on the server. All AitherOS internal context layers are disabled — only your input and the agent persona are active.

#### think (15 tokens)
Deep reasoning about any problem — code, research, strategy, creative, anything.

Parameters:
- `problem` (string, required): The problem, question, or task to reason about
- `context` (string): Supporting material — code, documents, data, prior analysis
- `depth` (string): "quick" (effort 3), "balanced" (effort 5), "deep" (effort 7), "max" (effort 9)
- `persona` (string): Agent persona — "aither" (general), "demiurge" (engineering), "lyra" (research/strategy), "athena" (security), "apollo" (performance), "hydra" (review)

Returns: Structured analysis with reasoning, conclusions, and recommendations.

#### analyze (15 tokens)
Analyze any artifact — code, document, data, spec, architecture diagram, log, config.

Parameters:
- `artifact` (string, required): The content to analyze
- `artifact_type` (string): "code", "document", "data", "log", "spec", "config", "auto"
- `question` (string): Specific question to answer about the artifact
- `focus` (string): "quality", "security", "performance", "correctness", "completeness", "clarity"
- `depth` (string): "quick", "balanced", "deep"

Returns: Structured analysis with findings, quality score (0-10), and recommendations. Automatically routes to the best agent persona for the artifact type.

#### explain (10 tokens)
Deep explanation of any subject for any audience level.

Parameters:
- `subject` (string, required): What to explain — paste code, describe a concept, ask about a process
- `context` (string): Additional context to ground the explanation
- `audience` (string): "beginner", "technical", "expert", "executive"
- `depth` (string): "quick", "balanced", "deep"

Returns: Summary, step-by-step walkthrough, key concepts, and examples.

#### debug (15 tokens)
Root cause analysis for any kind of problem.

Parameters:
- `problem` (string, required): Description of what's going wrong
- `artifact` (string): The artifact with the problem (code, config, log)
- `error_output` (string): Error messages, stack traces, log output
- `context` (string): What you were trying to do, recent changes, environment

Returns: Root cause, explanation, specific fix, and prevention strategy.

#### review (20 tokens, Developer+)
Multi-perspective review of any work product via Hydra agent (multi-reviewer persona).

Parameters:
- `artifact` (string, required): The work product to review
- `artifact_type` (string): "code", "document", "plan", "design", "proposal", "auto"
- `criteria` (string): Review criteria or standards to evaluate against
- `context` (string): Background — requirements, audience, constraints

Returns: Findings by severity (critical/high/medium/low/info), each with location, description, and suggested improvement. Strengths list and overall quality score.

#### plan (20 tokens, Developer+)
Structured planning for any task via Lyra agent (research/strategy persona).

Parameters:
- `goal` (string, required): What needs to be accomplished
- `context` (string): Background — existing work, team capabilities, domain knowledge
- `constraints` (string): Requirements, deadlines, budget, tech stack, policies
- `artifacts` (string): Reference materials — existing docs, specs, code to build on
- `depth` (string): "quick" (outline), "balanced" (detailed), "deep" (comprehensive with contingencies)

Returns: Ordered phases, detailed steps, dependencies, deliverables, risks with mitigations, and success criteria.

### Tier 2 — Tenant Memory & Knowledge (Pro+)

These tools build a persistent, tenant-isolated knowledge graph. Ingest your repos, docs, specs, and notes. The system learns your codebase and domain. All future tool calls can leverage this accumulated knowledge.

#### ingest (30 tokens)
Ingest an artifact into your tenant's knowledge graph.

Parameters:
- `content` (string, required): The content to ingest (text, code, structured data)
- `content_type` (string): "code", "document", "spec", "data", "config", "notes", "auto"
- `source_name` (string): Source identifier (e.g., "src/auth.py", "PRD-v2.md")
- `metadata` (string): Additional metadata as JSON string

Returns: Ingestion confirmation with node count, concepts extracted, and graph stats.

#### ingest_repo (100 tokens)
Clone and index an entire git repository.

Parameters:
- `repo_url` (string, required): Git repository URL (HTTPS only)
- `branch` (string): Branch to ingest (default: "main")
- `file_patterns` (string): Comma-separated glob patterns (e.g., "*.py,*.ts,*.md")

Returns: File count, graph node count, and estimated token cost. Timeout: 5 minutes.

#### build_memory_graph (80 tokens)
Build or rebuild the semantic search index from all ingested content.

Parameters:
- `rebuild` (string): "true" to rebuild from scratch, "false" for incremental update

Returns: Node count, edge count, embedding count, build duration.

#### query_context (5 tokens)
Search your knowledge graph with hybrid keyword + semantic search.

Parameters:
- `query` (string, required): Natural language query
- `max_results` (string): Maximum results (default: "10")

Returns: Ranked results with source, relevance score, and content snippets.

#### tenant_remember (3 tokens)
Store a discrete fact, decision, pattern, or learning.

Parameters:
- `content` (string, required): The fact, decision, or pattern to remember
- `category` (string): "decision", "pattern", "fact", "preference", "lesson", "general"

Returns: Confirmation with memory ID.

#### tenant_recall (3 tokens)
Recall memories and learnings from your knowledge base.

Parameters:
- `query` (string, required): What to recall — natural language
- `category` (string): Filter by category (optional)

Returns: Relevant memories ranked by relevance.

### Tier 3 — Expeditions (Enterprise)

Long-horizon multi-phase project orchestration with human-in-the-loop gates. The system decomposes your goal into phases and tasks, assigns specialized agents, and works through structured deliverables. Nothing deploys without your approval.

#### expedition_create (200 tokens)
Start a multi-phase project.

Parameters:
- `goal` (string, required): What the expedition should accomplish
- `context` (string): Background — existing work, domain knowledge
- `constraints` (string): Requirements, deadlines, tech stack, policies
- `artifacts` (string): Reference materials

Returns: Expedition ID, phase breakdown, estimated cost range, first gate checkpoint. Timeout: 2 minutes.

#### expedition_gate (10 tokens)
Approve or reject a checkpoint.

Parameters:
- `expedition_id` (string, required): The expedition ID
- `gate_id` (string, required): The gate checkpoint ID
- `decision` (string, required): "approve" or "reject"
- `feedback` (string): Instructions or revisions (required for reject)

#### expedition_collect (20 tokens)
Collect deliverables from completed phases.

Parameters:
- `expedition_id` (string, required): The expedition ID
- `phase` (string): Specific phase (empty = all completed)

Returns: Packaged deliverables — code, documents, reports, artifacts.

### Tier 4 — Dark Factory (Enterprise, Premium Markup)

Fully autonomous goal-directed execution. Submit a goal, and the dark factory runs multi-agent loops, self-modifies its approach, learns from failures, gates quality via Frontier Judge (Claude Opus), and auto-remediates. Three autonomy levels control how much human oversight is required.

#### factory_submit (500 tokens)
Submit a goal for autonomous execution.

Parameters:
- `goal` (string, required): The outcome you want (be specific and measurable)
- `context` (string): Background material, domain knowledge
- `constraints` (string): Hard constraints — budget, timeline, quality bar
- `artifacts` (string): Input materials to work with
- `autonomy` (string): "supervised" (pauses at every decision), "guided" (pauses at high-risk only), "autonomous" (runs to completion)
- `budget_tokens` (string): Maximum Aitherium tokens to spend (default: "10000")

Returns: Job ID, estimated cost range, execution plan, first checkpoint. Timeout: 2 minutes.

#### factory_decide (10 tokens)
Respond to a decision checkpoint.

Parameters:
- `job_id` (string, required): The factory job ID
- `decision_id` (string, required): The decision checkpoint ID
- `decision` (string, required): "approve", "reject", "modify"
- `feedback` (string): Instructions (required for reject/modify)

#### factory_collect (20 tokens)
Collect all artifacts from a completed job.

Parameters:
- `job_id` (string, required): The factory job ID

Returns: All produced artifacts — code, documents, analysis, reports, data.

## Pricing

### Token Economics

Every tool call costs Aitherium tokens: `cost = base_tokens x effort_multiplier x plan_discount`

Effort multipliers: quick (0.5x), balanced (1.0x), deep (2.5x), max (7.0x)

Plan discounts: Free (1.0x), Pro (0.8x), Team (0.6x)

### Two Tracks

Aitherium has two pricing tracks: MCP Cloud (self-serve, token-metered) and Sovereign Platform (managed deployment for businesses).

### MCP Cloud Plans

| Plan | Price | Tokens/Month | Key Features | Rate Limit |
|------|-------|-------------|-------------|------------|
| Free | $0 | 2,500 | think, analyze, explain, debug | 30 req/min |
| Pro | $29/mo | 100,000 | + review, plan, knowledge graph, swarm coding, 10 agents | 120 req/min |
| Team | $99/mo | 500,000 | + 10 seats, unlimited agents, expeditions, SSO, audit logging | 600 req/min |

Annual billing: 20% discount. Crypto accepted: SOL.

### Sovereign Platform (for businesses)

Dedicated AI workforce with unlimited inference, custom agents, and full data sovereignty.

| Component | Price | Description |
|-----------|-------|-------------|
| Initial deployment | from $20K | 3-month build: tenant setup, custom agent, integration, handoff |
| Monthly platform | from $2,500/mo | Dedicated infra, unlimited 24/7 inference, maintenance, direct access |
| Named agents | $500–1,500/mo each | Atlas (company brain), Demi (engineering), Lyra (research) |

Year 1 baseline: ~$48–52K. With named agents: ~$60–80K. Cloud equivalent: $300–480K/yr.

**Founding Partner Program**: 2 of 3 slots open. Pricing locked 24 months at 50–60% below standard rates. Contact: contact@aitherium.com

Machine-readable pricing: https://demo.aitherium.com/api/pricing

### Cost Preview

Before executing, check the cost:

```bash
curl -X POST https://gateway.aitherium.com/v1/external/estimate \
  -H "Content-Type: application/json" \
  -d '{"tool": "think", "effort": 5, "plan": "starter"}'
```

Response: `{"tool": "think", "base_cost": 15, "effort_multiplier": 1.0, "plan_discount": 1.0, "estimated_tokens": 15}`

## Account Management

### Check Balance

```bash
curl https://gateway.aitherium.com/v1/billing/balance \
  -H "Authorization: Bearer aither_sk_live_YOUR_KEY"
```

### Rotate API Key

```bash
curl -X POST https://gateway.aitherium.com/v1/billing/keys/refresh \
  -H "Authorization: Bearer aither_sk_live_YOUR_KEY"
```

Returns a new key. The old key is immediately invalidated.

## Agent Personas

When using `think`, you can select a persona optimized for different domains:

| Persona | Specialty | Best For |
|---------|-----------|----------|
| aither | General intelligence | Broad questions, multi-domain reasoning |
| demiurge | Software engineering | Code architecture, implementation, debugging |
| hydra | Multi-perspective review | Code review, document review, quality assessment |
| lyra | Research & strategy | Planning, research synthesis, strategic analysis |
| athena | Security | Security audits, threat modeling, vulnerability analysis |
| apollo | Performance | Performance optimization, bottleneck analysis, scaling |

## Error Codes

| HTTP Status | Error | Meaning |
|-------------|-------|---------|
| 401 | invalid_api_key | API key is invalid or expired |
| 402 | insufficient_balance | No tokens remaining — top up or upgrade plan |
| 403 | tool_not_available | Tool requires a higher plan tier |
| 429 | rate_limit_exceeded | Too many requests — retry after cooldown |
| 502 | service_unavailable | Backend temporarily unavailable |

## Data Isolation

- Tier 1 tools are stateless — nothing is stored
- Tier 2 memory is tenant-scoped — your data is isolated in `tenants/{your_id}/`
- Tier 3/4 use per-tenant expedition databases
- No cross-tenant queries are possible
- All AitherOS internal context (neurons, flux, affect) is disabled for external callers
- Rate locked for 12 months after sign-up

## Agent Development Kit (ADK)

Build your own agents that run locally and use Aitherium cloud inference:

```bash
pip install aither-adk
```

### Quick Start

```python
from adk import AitherAgent
from adk.elysium import Elysium

# Connect to Elysium (validates API key, fetches models)
ely = await Elysium.connect(api_key="aither_sk_live_...")

# Create an agent with cloud inference
agent = AitherAgent("my-agent", llm=ely.router)
response = await agent.chat("Hello from my custom agent!")
```

### Autonomous Agent Self-Registration (Full Flow)

Agents can fully self-onboard, fund their accounts, and start using inference without any human interaction:

#### Step 1: Register User Account

```
POST https://gateway.aitherium.com/v1/auth/register
Content-Type: application/json

{"email": "agent@example.com", "password": "secure-password-here", "display_name": "My Agent"}
```

Response: `{"ok": true, "user_id": "user_abc123", "message": "Verification email sent"}`

#### Step 2: Verify Email

```
POST https://gateway.aitherium.com/v1/auth/verify
Content-Type: application/json

{"email": "agent@example.com", "token": "verify-token-from-email"}
```

Response: `{"ok": true, "message": "Email verified"}`

#### Step 3: Login

```
POST https://gateway.aitherium.com/v1/auth/login
Content-Type: application/json

{"email": "agent@example.com", "password": "secure-password-here"}
```

Response: `{"ok": true, "token": "eyJhbGciOiJIUzI1NiJ9...", "expires_at": 1741234567}`

The `token` is a JWT. Use it as `Authorization: Bearer <token>` for subsequent calls.

#### Step 4: Get ACTA API Key (for metered inference)

```
POST https://gateway.aitherium.com/v1/billing/register
Content-Type: application/json

{"email": "agent@example.com"}
```

Response: `{"user_id": "user_abc123", "api_key": "aither_sk_live_YOUR_KEY_EXAMPLE", "balance": 2500, "plan": "explorer"}`

The `api_key` (starts with `aither_sk_live_`) is your permanent bearer token for inference and MCP tools.

#### Step 5: Fund Account (Optional — Autonomous Crypto Payment)

Send SOL to the Aitherium master wallet and verify:

```
# Transfer SOL on-chain to: 2pjRQhjWRCEfgqVmjR6DyB4UAXcqanRwvgFeu31EzCmb

# Then verify the transaction:
POST https://mcp.aitherium.com/acta/billing/crypto/verify-tx
Authorization: Bearer aither_sk_live_...
Content-Type: application/json

{"tx_signature": "5zT...", "wallet_address": "2pjRQhjWRCEfgqVmjR6DyB4UAXcqanRwvgFeu31EzCmb", "coin": "SOL", "amount": 0.5}
```

Response: `{"ok": true, "tokens_credited": 50000, "new_balance": 52500}`

#### Step 6: Register Agent on the Network

```
POST https://gateway.aitherium.com/v1/agents/register
Authorization: Bearer aither_sk_live_...
Content-Type: application/json

{
  "name": "my-support-bot",
  "capabilities": ["customer-support", "billing", "technical"],
  "description": "AI support agent for Acme Corp",
  "tools": ["search_database", "send_email", "create_ticket"]
}
```

Response: `{"ok": true, "agent": {"id": "agent_xyz789", "agent_name": "my-support-bot", ...}}`

#### Step 7: Use Inference

```
POST https://mcp.aitherium.com/v1/chat/completions
Authorization: Bearer aither_sk_live_...
Content-Type: application/json

{
  "model": "aither-orchestrator",
  "messages": [{"role": "user", "content": "Hello!"}]
}
```

Response: Standard OpenAI chat completion format.

### Client-Side Health Checks

Agents should validate backend health before starting operations:

```
# 1. Gateway health (auth, agent registry, billing)
GET https://gateway.aitherium.com/health
Expected: {"ok": true, "service": "AitherOS Gateway", "timestamp": "...", "version": "1.0.0"}

# 2. Inference health (LLM pipeline)
GET https://mcp.aitherium.com/health
Expected: {"status": "ok", ...}

# 3. Check your token balance
GET https://gateway.aitherium.com/v1/billing/balance
Authorization: Bearer aither_sk_live_...
Expected: {"balance": 2500, "plan": "explorer", "api_calls_today": 42}

# 4. List available models (confirms inference access)
GET https://mcp.aitherium.com/v1/models
Authorization: Bearer aither_sk_live_...
Expected: {"object": "list", "data": [{"id": "aither-small", ...}, ...]}

# 5. Check your registered agents
GET https://gateway.aitherium.com/v1/agents/mine
Authorization: Bearer aither_sk_live_...
Expected: {"ok": true, "agents": [...]}

# 6. Discover other agents on the network
GET https://gateway.aitherium.com/v1/agents/discover?limit=10
Expected: {"ok": true, "agents": [...], "total": N}
```

If any health check fails, the agent should retry with exponential backoff and fall back to local inference if available.

### Using ADK for Health Checks

```python
from adk.elysium import Elysium

ely = Elysium(api_key="aither_sk_live_...")

# Gateway reachable?
healthy = await ely.health()  # True/False

# What models can I use?
models = await ely.models()  # [{"id": "aither-small", ...}, ...]

# My registered agents
agents = await ely.my_agents()  # [{"id": "agent_xyz", ...}, ...]
```

### Available Models by Tier

| Model | Tier | Cost (tokens/1K) | Backend | Context |
|-------|------|-------------------|---------|---------|
| aither-small | Free | 1 | Ollama (llama3.2:3b) | 8K |
| aither-orchestrator | Developer+ ($20/mo) | 3 | vLLM (nemotron-8b) | 32K |
| aither-reasoning | Pro+ ($99/mo) | 10 | vLLM (deepseek-r1:14b) | 32K |
| aither-vision | Pro+ ($99/mo) | 8 | vLLM | 16K |
| aither-coding | Pro+ ($99/mo) | 5 | vLLM | 32K |

### OpenAI SDK Compatibility

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://mcp.aitherium.com/v1",
    api_key="aither_sk_live_YOUR_KEY",
)

response = client.chat.completions.create(
    model="aither-orchestrator",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

### Agent Management Endpoints

- `POST /v1/agents/register` — Register agent. Auth required.
- `GET /v1/agents/discover` — Search agents. Params: `capability`, `limit`.
- `GET /v1/agents/mine` — List your agents. Auth required.
- `DELETE /v1/agents/{id}` — Remove agent. Auth required, owner-only.

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `AITHER_API_KEY` | ACTA API key (aither_sk_live_...) |
| `AITHER_GATEWAY_URL` | Override gateway URL |
| `AITHER_INFERENCE_URL` | Override inference URL |

## Live Portfolio

Deployed applications built on the Aitherium platform:

- **AitherOS Demo**: https://demo.aitherium.com — Full platform with AI chat, agents, and dashboard
- **Wildroot Alchemy**: https://wildroot.aitherium.com — AI-powered botanical care storefront
- **Chelle**: https://chelle.aitherium.com — Custom AI agent/assistant deployment
- **Gargbot**: https://garg.aitherium.com — Custom AI agent with specialized persona
- **Roboflow**: https://roboflow.aitherium.com — Computer vision pipeline integration

## Self-Hosting

AitherOS is open source. Deploy the full stack on your own hardware — no subscription required:

```bash
git clone https://github.com/Aitherium/aither
cd aither
docker compose -f docker-compose.aitheros.yml --profile chat-full up -d
```

## Trust & Security

- Open source: https://github.com/Aitherium/aither
- Tenant-isolated data (zero cross-tenant leakage)
- HMAC-SHA256 capability-based security (default deny)
- Security contact: security@aitherium.com
- Security policy: https://demo.aitherium.com/.well-known/security.txt
- Terms: https://demo.aitherium.com/terms
- Privacy: https://demo.aitherium.com/privacy

## Support & Links

- Enterprise: enterprise@aitherium.com
- Pricing: https://demo.aitherium.com/pricing
- Pricing API (JSON): https://demo.aitherium.com/api/pricing
- Agent card (A2A): https://demo.aitherium.com/.well-known/agent.json
- Plugin manifest: https://demo.aitherium.com/.well-known/ai-plugin.json
- OpenAPI spec: https://demo.aitherium.com/api/openapi
- Status: https://gateway.aitherium.com/health
- GitHub: https://github.com/Aitherium/aither
- Solana wallet: 2pjRQhjWRCEfgqVmjR6DyB4UAXcqanRwvgFeu31EzCmb