Connect your AI agent (MCP)

Amatya Tests speaks MCP — 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. It is shown once — store it like a password.
2. Add the server to your agent:

Claude Code

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:

{
  "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 is scope-narrowed to the bank only.