@aptora/mcp

MCP server for Aptora. Lets Claude Code, Claude Desktop, Cursor, or any MCP client create and edit assessments, upload starter workspaces, invite candidates, and pull grading results — straight from your editor or agent.

Setup

1. Create an API key in the Aptora dashboard under Integrations → API Keys. The key acts with the full manager permissions of the user who created it — treat it like a password.

2. Register the server with your MCP client:

Claude Code:

claude mcp add aptora -e APTORA_API_KEY=apt_... -- npx -y @aptora/mcp

Claude Desktop / Cursor / other JSON-configured clients:

{
    "mcpServers": {
        "aptora": {
            "command": "npx",
            "args": ["-y", "@aptora/mcp"],
            "env": {
                "APTORA_API_KEY": "apt_..."
            }
        }
    }
}

3. Try it — ask your agent to "list my Aptora assessments" or "create an Aptora assessment for a senior backend role and invite [email protected]".

Environment variables

| Variable | Default | Purpose | |---|---|---| | APTORA_API_KEY | required | API key from the dashboard | | APTORA_BASE_URL | https://api.tryaptora.com | Backend origin (set http://localhost:4001 for local dev) | | APTORA_APP_URL | https://app.tryaptora.com | Used to build candidate interview links |

Tools

• get_authoring_guide — how to write an assessment: fields, the required ProseMirror problem format, environment constraints, setup hooks and black-box services, personas, grading
• get_dry_run_guide — how to QA an assessment by taking it as a test candidate in a browser
• whoami — verify the key and see whose account it acts as
• list_assessments / get_assessment
• create_assessment / update_assessment — pass workspace_directory to upload a local directory (VCS/deps/build-output/.env excluded) as the candidate's starter workspace; problem must be a ProseMirror JSON document
• create_interview — create an interview and return its link without emailing anyone (also used for dry runs)
• invite_candidate — create an interview and send the real invitation email
• list_interviews — statuses plus grading summaries
• get_grading_results — the full grading report for an interview
• get_workspace_snapshot — the candidate's final workspace files

The server also ships instructions that MCP clients load into the model's context (author with the guide, dry-run before inviting, never email without being asked) and a dry_run prompt — in Claude Code, /mcp__aptora__dry_run <assessment_id>. Both guides are served by the backend (GET /api/v1/guides/:name), so they always match the deployed platform.

Development (this repo)

The server is a thin stdio client for the backend's /api/v1 surface (Basic auth with an Aptora API key; never superuser powers). Build from the repo root (npm run build), then point your MCP client at the local bundle instead of npx:

claude mcp add aptora -e APTORA_API_KEY=apt_... -- node /path/to/aptora/packages/mcp/dist/index.js

dist/index.js is esbuild-bundled: the workspace-only deps (@aptora/types, @aptora/ignore) are inlined at build time and live in devDependencies, so the published tarball installs standalone.

Releasing

package.json is the only place the version lives: the server reports it over MCP, and the build writes the MCP Registry manifest (dist/server.json) from it. To release, bump version, then from this directory:

npm publish                                # prepublishOnly rebuilds dist/
mcp-publisher login dns --domain tryaptora.com --private-key "$MCP_REGISTRY_PRIVATE_KEY"
mcp-publisher publish dist/server.json     # after npm: the registry checks the npm mcpName