# Aetherya MCP Setup

Aetherya exposes its behavioral-simulation engine as an MCP (Model Context Protocol) server. Any MCP-capable agent — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex — can connect and call the simulation tools directly from the editor.

## Install: npm only (`npx`)

The only supported install path is the published `@aetherya/mcp` package on npm, run with `npx`.

**Claude Code:**

```bash
claude mcp add aetherya -- npx -y @aetherya/mcp
npx -y @aetherya/mcp auth
```

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

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

`npx` pulls `@aetherya/mcp` from npm and runs it on demand, so it stays current automatically.

## Discovery-first authentication

Run `npx @aetherya/mcp auth` on first use. The client discovers Aetherya's protected-resource and authorization-server metadata, starts a `service_auth` or `anonymous` registration, and opens the human claim URL when a workspace binding is required. The human reviews exact capabilities and enters the six-digit code. The MCP client stores the service-signed identity assertion locally (mode `0600` when a file is used), exchanges it for a 15-minute access token at runtime, and re-exchanges it to refresh. No refresh token or long-lived access token is stored.

Agent access tokens are workspace-bound, so no workspace header is needed. Revoke from Settings → API & agent access or with `POST /oauth2/revoke`. Unknown API routes and admin, billing, membership, connections, approvals, memory, and internal endpoints are not available to agent tokens.

## Legacy API key

Get a legacy key from the Aetherya dashboard → **Settings → API Keys**. Keys start with `aeth_live_`. Existing hosts may continue using `AETHERYA_API_KEY`; the MCP auth identity takes precedence when configured and credentials are never logged.

## Tool catalog

| Tool | Description |
|---|---|
| `aetherya_audit_site` | Run a behavioral simulation of a URL — predicted UX friction, hesitation, drop-off, and messaging clarity issues with fixes. |
| `aetherya_get_audit_result` | Fetch an audit's findings by job_id. Audits run async — poll this while a simulation is running. |
| `aetherya_list_audiences` | List your synthetic audiences. |
| `aetherya_create_audience` | Generate new synthetic personas from a plain-language description. |
| `aetherya_test_copy` | Test a headline, value proposition, or copy variant against a synthetic audience. |
| `aetherya_ask_audience` | Pose an open-ended question to a synthetic audience and get a predicted, in-character response. |

## Roadmap

A remote Streamable HTTP transport (no local process required) is on the roadmap. Follow [/agent#status](/agent#status) for current protocol version information.

---

*For API access without MCP, see [/agent.md](/agent.md) or [the API quickstart](/agent#act).*