Praxicraft Assess MCP

Official Model Context Protocol server for the Praxicraft Assess Public API.

Connect Cursor, Claude Code, Claude Desktop, Codex, or any MCP client so an agent can invite candidates, manage assessments and pipelines, register webhooks, and fetch results — with your permission.

npx -y @praxicraft/assess-mcp

Requires Node.js 18+. Product docs: docs.praxicraft.com/assess-mcp · Build with agents

Prefer one install for API MCP + docs search + skills? Use the Assess Agent Plugin.

Table of Contents

• Two ways to connect
• Authentication
• Quickstart
  • Hosted HTTP (Cursor / Claude Code)
  • Stdio (API key)
• What agents can do
• Live vs Test mode
• Errors
• Requirements & support
• License

---

Two ways to connect

Mode	Best for	Auth
Hosted HTTP	Interactive IDE sessions	Browser OAuth at https://assess.praxicraft.com/mcp (always live)
Stdio (npx @praxicraft/assess-mcp)	CI, locked-down machines, Test mode	PRAXICRAFT_API_KEY (ct_live_… or ct_test_…)

Hosted OAuth is the easiest path in Cursor and Claude. Use stdio when you need a ct_test_ key or a non-interactive environment.

---

Authentication

Hosted (OAuth)

No API key in your config. The first tool call opens a browser consent screen. Owners, admins, and developers can approve.

Hosted sessions are always live mode.

Stdio (API key)

Create an organisation API key:

Assess → Developer → API Keys → create key → copy ct_live_… or ct_test_… (shown once).

export PRAXICRAFT_API_KEY="ct_test_xxxxxxxxxxxxxxxx"
# optional
export PRAXICRAFT_API_BASE_URL="https://assess.praxicraft.com"

Never commit API keys. Prefer environment variables or a secrets manager.

IP allowlists on API keys apply to Public API / stdio MCP requests. They do not apply to hosted OAuth. Use a dedicated key with an empty allowlist for stdio if other keys are CIDR-restricted.

Scopes and rotation: Authentication

Recommended scopes

Flow	Scopes
Invite + notify	assessments:read, invitations:write, candidates:read, webhooks:write
Pipelines	pipelines:read, pipelines:write, webhooks:write
Read-only	assessments:read, candidates:read, organisation:read

---

Quickstart

Hosted HTTP (Cursor / Claude Code)

Add to your MCP settings:

{
  "mcpServers": {
    "praxicraft-assess": {
      "url": "https://assess.praxicraft.com/mcp"
    }
  }
}

Claude Code example:

{
  "mcpServers": {
    "praxicraft-assess": {
      "type": "http",
      "url": "https://assess.praxicraft.com/mcp"
    }
  }
}

Restart the client, then try: “List my Assess assessments and invite me to the first active one.”

Stdio (API key)

{
  "mcpServers": {
    "praxicraft-assess": {
      "command": "npx",
      "args": ["-y", "@praxicraft/assess-mcp"],
      "env": {
        "PRAXICRAFT_API_KEY": "ct_test_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

From source (contributors):

git clone https://github.com/praxicraft-platform/praxicraft-assess-mcp.git
cd praxicraft-assess-mcp
npm ci
npm test
npm run smoke

---

What agents can do

Tools map to the Assess Public API (/api/v1/public/…). Coverage includes:

Area	Examples
Assessments	List, create, update, activate, attach cases
Invitations	Invite, bulk invite, remind, cancel
Results	List / retrieve by invite_token
Webhooks	Create destinations, test, list deliveries, retry
Pipelines	List, enroll, hold / unhold / reject
Interviews	List / manage interview rooms
Organisation	Profile, quota, squads, audit (plan-gated)
Integrations	Connector status (no secrets in responses)

Responses are flat JSON (same shape as the Public API — no { "data": … } wrapper).

Remind agents to respect plan limits and to branch on error.code.

---

Live vs Test mode

	Live (ct_live_… / hosted OAuth)	Test (ct_test_… via stdio)
Data	Production org	Isolated test data
Webhooks	Live destinations only	Test destinations only

A test candidate.passed never hits a live Slack or HTTPS destination. See Live and Test mode.

---

Errors

Public API errors look like:

{ "error": { "code": "SOME_CODE", "message": "…", "details": {} } }

Always branch on error.code. Reference: Errors

---

Requirements & support

• Node.js 18+ (stdio package)
• Assess plan that includes API keys (see plan limits)
• Product docs: docs.praxicraft.com
• Agent Plugin (API + docs Knowledge MCP + skills): praxicraft-assess-agent-plugin
• Issues: GitHub Issues
• Email: support@praxicraft.com

Maintainers deploying the hosted /mcp service: see DEPLOYMENT.md.

---

License

MIT