# Aitherium Integration: MCP Client Configuration

Connect any MCP-compatible client (Claude Code, Cursor, Windsurf, VS Code, etc.) to Aitherium's cloud MCP server.

## Prerequisites

1. An Aitherium API key (register at `POST https://gateway.aitherium.com/v1/billing/register`)
2. An MCP-compatible client

## MCP Server Configuration

### Claude Code

Add to your `.claude/settings.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

Add to your Cursor MCP settings (Settings > MCP Servers):

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

### Windsurf

Add to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "aitherium": {
      "serverUrl": "https://mcp.aitherium.com/mcp",
      "transport": "streamable-http",
      "env": {
        "AITHER_API_KEY": "aither_sk_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

### VS Code (Copilot MCP)

Add to your VS Code `settings.json`:

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

### Generic MCP Client (any SDK)

```python
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    url="https://mcp.aitherium.com/mcp",
    headers={"Authorization": "Bearer aither_sk_live_YOUR_KEY_HERE"}
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print(f"Available tools: {[t.name for t in tools.tools]}")

        # Use a tool
        result = await session.call_tool("think", {
            "problem": "What's the best way to structure a microservice?",
            "depth": "deep"
        })
        print(result.content[0].text)
```

## Available MCP Tools

After connecting, these tools become available:

### Free Tier (2,500 tokens/month)

| Tool | Description | Cost |
|------|-------------|------|
| `think` | Deep reasoning with persona selection | 15 tok |
| `analyze` | Analyze code, docs, data, logs | 15 tok |
| `explain` | Explain any subject at any level | 10 tok |
| `debug` | Root cause analysis | 15 tok |

### Developer Tier ($29/mo)

| Tool | Description | Cost |
|------|-------------|------|
| `review` | Multi-perspective code/work review | 20 tok |
| `plan` | Structured task planning | 20 tok |

### Pro Tier ($99/mo)

| Tool | Description | Cost |
|------|-------------|------|
| `ingest` | Add to knowledge graph | 30 tok |
| `ingest_repo` | Index entire git repo | 100 tok |
| `build_memory_graph` | Build semantic search index | 80 tok |
| `query_context` | Search knowledge graph | 5 tok |
| `tenant_remember` | Store persistent memories | 3 tok |
| `tenant_recall` | Recall stored memories | 3 tok |

### Enterprise Tier

| Tool | Description | Cost |
|------|-------------|------|
| `expedition_create` | Multi-phase orchestrated project | 200 tok |
| `expedition_gate` | Approve/reject checkpoint | 10 tok |
| `factory_submit` | Fully autonomous execution | 500 tok |

## Tool Usage Examples

### Think deeply about a problem

```
Tool: think
Arguments: {
  "problem": "How should I structure authentication for a multi-tenant SaaS?",
  "depth": "deep",
  "persona": "athena"
}
```

### Analyze code

```
Tool: analyze
Arguments: {
  "artifact": "def process(data):\n  return eval(data['expression'])",
  "artifact_type": "code",
  "focus": "security"
}
```

### Ingest a document into your knowledge graph

```
Tool: ingest
Arguments: {
  "content": "Our API rate limits are 100 req/min for free, 1000 for pro...",
  "content_type": "documentation",
  "source_name": "api-limits.md"
}
```

### Start a multi-phase project

```
Tool: expedition_create
Arguments: {
  "goal": "Refactor the authentication module to support OAuth2 + SAML",
  "context": "Current auth is password-only. Need to support enterprise SSO.",
  "constraints": ["Backward compatible", "No downtime", "Must pass security audit"]
}
```

## OpenAI-Compatible Inference (Alternative)

If your client doesn't support MCP but supports OpenAI-compatible APIs:

```
Base URL: https://mcp.aitherium.com/v1
API Key: aither_sk_live_YOUR_KEY_HERE
Models: aither-small, aither-orchestrator, aither-reasoning, aither-vision, aither-coding
```

This works with any OpenAI SDK, LangChain, LlamaIndex, or HTTP client.

## Troubleshooting

| Issue | Fix |
|-------|-----|
| "Tool not found" | Check API key tier — some tools require paid plans |
| "Connection refused" | Verify URL is `https://mcp.aitherium.com/mcp` (with /mcp) |
| "401 Unauthorized" | Check API key format: must start with `aither_sk_live_` |
| "SSE timeout" | Some tools take 30-60s for deep reasoning. Increase timeout. |
| Tools not showing | Restart your MCP client after adding the configuration |