# Aetherya MCP Setup

Aetherya ships an MCP (Model Context Protocol) server, `@aetherya/mcp` on npm. Any MCP client (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex) can run simulations through it.

## 1. Get an API key

The server authenticates with an Aetherya API key (`aeth_live_...`). A human creates the account at https://app.aetherya.ai/signup (Google, or email plus an emailed code) and creates the key at https://app.aetherya.ai/dashboard/settings?tab=api-keys. The Free plan needs no card.

## 2. Install

**Claude Code:**

```bash
claude mcp add aetherya -e AETHERYA_API_KEY=aeth_live_... -- npx -y @aetherya/mcp
```

**Claude Desktop / Cursor / Windsurf / VS Code (mcpServers config):**

```json
{
  "mcpServers": {
    "aetherya": {
      "command": "npx",
      "args": ["-y", "@aetherya/mcp"],
      "env": { "AETHERYA_API_KEY": "aeth_live_..." }
    }
  }
}
```

`npx` runs the latest published version on demand. The server talks to `https://api.aetherya.ai`; set `AETHERYA_API_BASE_URL` only to point it elsewhere.

## Or use the hosted server

No local process: point any client that can send a custom header at `https://mcp.aetherya.ai/mcp` (streamable HTTP) with `Authorization: Bearer aeth_live_...`. Listing tools is open; calling one needs the key. It has the same 27 tools as the npm package, except that `aetherya_pretest_video` takes a `video_url`, not a local `video_path`.

```bash
claude mcp add --transport http aetherya https://mcp.aetherya.ai/mcp --header "Authorization: Bearer aeth_live_..."
```

## 3. Run a simulation

1. `aetherya_plan_study` with the objective in plain English. Aetherya designs the study, picks or builds the audience, and returns a price (`needs_price_confirmation`) or a clarifying question.
2. Confirm the price with your user, then `aetherya_confirm_study` with the quoted figure. Nothing is spent before this.
3. `aetherya_get_result` or `aetherya_get_brief` to collect the answer. Simulations usually take minutes; a `running` status is normal.

For a few-second answer on 2–5 headlines or offers, use `aetherya_read`. If you already know the method, `aetherya_list_capabilities` and `aetherya_estimate` show the options and prices, and `aetherya_test_copy`, `aetherya_audit_site`, and the other run tools take exact inputs. Your client lists every tool with its schema.

Every result is a simulated prediction from a synthetic audience, not real-user data.

## Not available yet

- Sign-in connectors that use OAuth instead of a key, such as claude.ai and ChatGPT. The hosted server accepts API keys only.
- Delegated sign-in without an API key (`npx @aetherya/mcp auth`). See [/auth.md](/auth.md) for status.

---

*Agent overview: [/agent.md](/agent.md). HTTP API: [/openapi.json](/openapi.json).*