# Connect your AI agent (MCP)

Amatya Tests speaks [MCP](https://modelcontextprotocol.io) — the open protocol
coding agents use to call tools. Connect once and your agent can ingest
question papers, build tests, send links, and evaluate written answers, all
against your real account with your real limits.

## Setup

1. Mint an **API token** in [Agents & API](/tests/app/tokens). It is shown once — store it like a password.
2. Add the server to your agent:

**Claude Code**

```bash
claude mcp add amatya-tests --transport http https://siddhixsys.com/api/tests-mcp --header "Authorization: Bearer atk_YOUR_TOKEN"
```

**Cursor / any HTTP MCP client** — `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "amatya-tests": {
      "url": "https://siddhixsys.com/api/tests-mcp",
      "headers": { "Authorization": "Bearer atk_YOUR_TOKEN" }
    }
  }
}
```

**stdio-only clients** — bridge with `npx mcp-remote https://siddhixsys.com/api/tests-mcp --header "Authorization: Bearer atk_YOUR_TOKEN"`.

## The loop good agents run

1. `get_limits` — know the caps before starting.
2. `add_questions` — batch insert with a `client_ref` per question; **read the
   per-item report** (inserted / exists / error) instead of assuming success.
   Retries with the same `client_ref` are no-ops, never duplicates.
3. `create_test` → `create_section` (marking scheme) → `add_test_questions`
   (explicit ids, or a random `pool` by topic/difficulty that always respects
   the test's languages).
4. `publish_test` — validation errors name exactly what to fix; `language_gaps`
   lists which question is missing which language.
5. `get_preview_link` — **take the test yourself** (the preview attempt never
   counts) and sanity-check the paper.
6. `add_takers` → `get_links` / `send_invites` (previews first; queuing real
   email requires `confirm: true` — ask your human).
7. After submissions: `list_attempts` → `get_attempt` (answers beside the
   rubric) → `evaluate_answer` → `publish_results`.

Every response ends with your remaining entitlements, so a well-behaved agent
never discovers a cap by failing.

## Rate limits & scopes

Free accounts: 60 tool calls/minute. Pro: 240. Tokens carry scopes
(`bank:write`, `tests:write`, `results:write`, `send`, …) — a
[delegate token](/docs/tokens) is scope-narrowed to the bank only.