# Pro Evaluation System — Agentic API (for AI agents)

Bearer-authed tools to run a full assessment lifecycle (programs, participants, surveys, mail, scoring, results). Human docs: https://www.proevaluationsystem.com/mcp

## Connect

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

```
claude mcp add --transport http pes \
  https://www.proevaluationsystem.com/_api/mcp/server.php \
  --header "Authorization: Bearer $PES_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": {
    "pes": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.proevaluationsystem.com/_api/mcp/server.php",
        "--header", "Authorization:Bearer eak_YOUR_KEY_HERE"]
    }
  }
}
```

Raw REST: `POST https://www.proevaluationsystem.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.**

### Reads (free)

| tool | scope | cost | |
|---|---|---|---|
| `read_evidence` | `read:evidence` | free |  |
| `read_frameworks` | `read:frameworks` | free |  |
| `read_results` | `read:results` | free |  |
| `read_sessions` | `read:sessions` | free |  |
| `read_skills` | `read:skills` | free |  |

### 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 |  |

### Participants & raters

| tool | scope | cost | |
|---|---|---|---|
| `participants_add` | `participants:add` | 1 cr |  |
| `participants_add_evaluator` | `participants:add_evaluator` | 1 cr |  |
| `participants_bulk_import` | `participants:bulk_import` | 1×N cr | ⚠ approval |
| `participants_list` | `participants:list` | free |  |
| `participants_remove` | `participants:remove` | 1 cr | ⚠ approval |
| `participants_set_role` | `participants:set_role` | 1 cr |  |
| `participants_status` | `participants:status` | free |  |

### Surveys

| tool | scope | cost | |
|---|---|---|---|
| `survey_add_question` | `survey:add_question` | 1 cr |  |
| `survey_add_skill` | `survey:add_skill` | 1 cr |  |
| `survey_create` | `survey:create` | 5 cr |  |
| `survey_duplicate` | `survey:duplicate` | 5 cr |  |
| `survey_get` | `survey:get` | free |  |
| `survey_list` | `survey:list` | free |  |
| `survey_publish` | `survey:publish` | 10 cr | ⚠ approval |
| `survey_set_scale` | `survey:set_scale` | 1 cr |  |
| `survey_unpublish` | `survey:unpublish` | 5 cr | ⚠ approval |
| `survey_update` | `survey:update` | 2 cr |  |

### Frameworks (rubrics-as-data)

| tool | scope | cost | |
|---|---|---|---|
| `frameworks_add_dimension` | `frameworks:add_dimension` | 2 cr |  |
| `frameworks_add_indicator` | `frameworks:add_indicator` | 1 cr |  |
| `frameworks_create` | `frameworks:create` | 5 cr |  |
| `frameworks_update` | `frameworks:update` | 2 cr |  |
| `frameworks_validate` | `frameworks:validate` | free |  |

### Mail

| tool | scope | cost | |
|---|---|---|---|
| `mail_create_template` | `mail:create_template` | 2 cr |  |
| `mail_list_templates` | `mail:list_templates` | free |  |
| `mail_preview` | `mail:preview` | 1 cr |  |
| `mail_send_bulk` | `mail:send_bulk` | 1×N cr | ⚠ approval · Tier 1+ |
| `mail_send_invites` | `mail:send_invites` | 1 cr | ⚠ approval |
| `mail_send_one` | `mail:send_one` | 1 cr |  |
| `mail_send_reminders` | `mail:send_reminders` | 1 cr | ⚠ approval |
| `mail_status` | `mail:status` | free |  |
| `mail_update_template` | `mail:update_template` | 1 cr |  |

### Scoring

| tool | scope | cost | |
|---|---|---|---|
| `calculate_run` | `calculate:run` | 20 cr | ⚠ approval |
| `calculate_status` | `calculate:status` | free |  |

### Results & reports

| tool | scope | cost | |
|---|---|---|---|
| `report_create` | `report:create` | 5 cr |  |
| `report_list` | `report:list` | free |  |
| `results_export` | `results:export` | 2 cr |  |
| `results_get` | `results:get` | 1 cr |  |

### Agent write-backs

| tool | scope | cost | |
|---|---|---|---|
| `write_bias_flag` | `write:bias_flag` | free |  |
| `write_devplan` | `write:devplan` | 2 cr |  |

### Interactive apps (MCP Apps)

| tool | scope | cost | |
|---|---|---|---|
| `debrief_app` | `debrief:app` | 1 cr |  |
| `report_app` | `report:app` | 1 cr |  |

### Evidence & AoL

| tool | scope | cost | |
|---|---|---|---|
| `evidence_put` | `evidence:put` | 1 cr |  |
| `export_aol_bundle_okf` | `export_aol_bundle_okf` | 2 cr |  |

---
Eureka Simulations tools are on a separate surface: https://www.eurekasimulations.com/mcp

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