# Eureka Simulations — Agentic API (for AI agents)

Bearer-authed tools to author and run live business simulations — deploy, hand out team logins, advance rounds, read rubric scores. Human docs: https://www.eurekasimulations.com/mcp

## Connect

**Claude Code** (native HTTP transport) — export your key first (`export EUREKA_API_KEY=eak_...`):

```
claude mcp add --transport http eureka \
  https://www.eurekasimulations.com/_api/mcp/server.php \
  --header "Authorization: Bearer $EUREKA_API_KEY"
```

**Claude Desktop / Cursor** (via the `mcp-remote` bridge) — put the key **literally** in the header; `${VARS}`/`env` are NOT expanded, and there is **no space** after the colon:

```jsonc
{
  "mcpServers": {
    "eureka": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.eurekasimulations.com/_api/mcp/server.php",
        "--header", "Authorization:Bearer eak_YOUR_KEY_HERE"]
    }
  }
}
```

Raw REST: `POST https://www.eurekasimulations.com/_api/mcp_<tool>.php` with header `Authorization: Bearer eak_...` and a JSON body. Call `whoami` for your scopes/tier/balance and `tools/list` for the tools + input schemas your key allows. The MCP tool name is the scope with `:` replaced by `_`.

## Rules for agents

- Reads and `*_status` tools are free; other writes cost credits (see tables).
- **Risky writes need a human.** The first call returns HTTP 409 `{"status":"approval_required","approval_id":N}` — the token is NOT returned to you. Ask the user to approve it (Approvals dashboard or the emailed link); they give you a 40-hex token; re-call the SAME tool with it in the `approval_token` argument. The token is single-use and bound to that exact payload. Never fabricate a token; never loop-retry a 409.
- Report only numbers that came from a tool result, never model memory.
- You only see tools your key is granted; a 403 means the scope isn't granted.

## Tools

Cost in credits (0 = free); `×N` multiplies by recipients/rows. **⚠ = needs approval.**

### Express — author & run live sessions

| tool | scope | cost | |
|---|---|---|---|
| `express_create` | `express:create` | 5 cr |  |
| `express_session_control` | `express:session:control` | 1 cr |  |
| `express_session_create` | `express:session:create` | 5 cr |  |
| `express_session_get` | `express:session:get` | free |  |
| `express_session_links` | `express:session:links` | free |  |
| `express_session_list` | `express:session:list` | free |  |
| `express_session_notepad` | `express:session:notepad` | free |  |
| `express_session_update` | `express:session:update` | 2 cr |  |
| `express_update` | `express:update` | 2 cr |  |

### AI authoring

| tool | scope | cost | |
|---|---|---|---|
| `ai_usf_retrofit` | `ai:usf_retrofit` | 50 cr |  |

### Programs & cohorts

| tool | scope | cost | |
|---|---|---|---|
| `program_announce` | `program:announce` | 2 cr |  |
| `program_create` | `program:create` | 5 cr |  |
| `program_list` | `program:list` | free |  |
| `program_start` | `program:start` | 5 cr | ⚠ approval |
| `program_update` | `program:update` | 2 cr |  |

### Reads (free)

| tool | scope | cost | |
|---|---|---|---|
| `read_frameworks` | `read:frameworks` | free |  |
| `read_sessions` | `read:sessions` | free |  |

---
Pro Evaluation System tools are on a separate surface: https://www.proevaluationsystem.com/mcp

_Generated by `docs/api/generate.php` from the live scope catalog — do not hand-edit._