@curriculo/mcp-server

Model Context Protocol server for the Curriculo ATS. Lets agents drive jobs, applicants, interviews, and candidate search via the ATS API — usable in Claude Desktop, Claude Code, Cursor, Codex, Continue, Goose, and any other MCP-aware client.

Status: v0.3.0 — 25 tools live (jobs, applicants, candidate search, interviews, agent-graph resume evaluation, inbox/email, automations, dashboard/analytics, import). Browser-based email login. stdio transport; HTTP transport is the next release.

Quick start

1. Install + sign in

npx -y @curriculo/mcp-server login

The CLI opens https://ats.curriculo.me/cli-auth?session=… in your browser. Sign in with your work email (Clerk handles Google + email), pick the org you want, and approve. The token gets saved to ~/.curriculo/credentials.json (mode 0600).

Curriculo MCP login
API URL: https://api.curriculo.me/api/v2

Opening https://ats.curriculo.me/cli-auth?session=cas_X9kT2rL4y8w
(If your browser didn't open, paste the URL above.)

Waiting for you to finish in the browser....

✓ Logged in as [email protected] (org: Acme Recruiting)
  Credential saved to /home/you/.curriculo/credentials.json

Verify:

npx -y @curriculo/mcp-server whoami
npx -y @curriculo/mcp-server --doctor

2. Add to your MCP client

After login, the credential is found automatically by every stdio client. No env var to copy.

Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) — add:

{
  "mcpServers": {
    "curriculo": {
      "command": "npx",
      "args": ["-y", "@curriculo/mcp-server"]
    }
  }
}

Cursor

~/.cursor/mcp.json — same shape.

Codex CLI

~/.codex/mcp.json — same shape.

Continue · Goose · any MCP CLI

Add the same mcpServers entry to that tool's config — they all speak the same stdio protocol.

3. Restart your client

The agent now sees the full Curriculo ATS tool set (25 tools).

Alternative: manual PAT (no login)

If you'd rather paste a token (e.g. in a CI environment), generate one at https://ats.curriculo.me → Settings → Developers → New key, copy the raw pat_…, and pass it via env:

{
  "mcpServers": {
    "curriculo": {
      "command": "npx",
      "args": ["-y", "@curriculo/mcp-server"],
      "env": { "CURRICULO_API_KEY": "pat_your_token_here" }
    }
  }
}

Resolution order is flag → env → credentials file — any of the three works.

Configuration

| Variable | Default | Description | |---|---|---| | CURRICULO_API_KEY | (from credentials file if set) | Raw Personal Access Token, must start with pat_ | | CURRICULO_API_URL | https://api.curriculo.me/api/v2 | core-api base URL override (dev: http://localhost:8082/api/v2) | | CURRICULO_DEBUG | 0 | Set to 1 for verbose logging to stderr |

CLI flags:

curriculo-mcp [options]                          Run as MCP stdio server (default)
curriculo-mcp login [--api-url url] [--no-browser]   Sign in with email; save credentials
curriculo-mcp logout                             Delete the local credential file
curriculo-mcp whoami                             Print user/org for current credential

Options (default action):
  --http                run HTTP transport (NOT implemented in v0.3.0)
  --port <n>            HTTP port (default: 3333)
  --api-url <url>       override API base URL
  --api-key <key>       override API key (prefer `login` or env var)
  --doctor              verify auth + list tools, then exit
  --debug               verbose logging to stderr
  -v, --version         print version
  -h, --help            print help

Tools

All tools are org-scoped server-side by your credential.

Identity

• whoami — authenticated ATS user + current organization.

Jobs

• list_jobs · get_job · create_job · update_job_status

Applicants

• list_applicants · get_applicant · move_applicant_stage · add_applicant_note · get_applicant_resume_text

Search

• search_candidates — semantic/Context-Graph search across the org's candidates.

Interviews

• list_interviews · schedule_interview

Agent graph (resume processing + evaluation)

• get_applicant_evaluation — suitability score, AI tags, summary, gap status (Phase 2 output).
• reprocess_resume — re-run the parse → evaluate → graph-ingest pipeline (Phase 1 + 2).

Inbox & email

• list_inbox_emails · get_inbox_stats · get_applicant_email_thread · reply_to_applicant_email · send_bulk_email

Automations

• list_job_automations · get_automation_executions

Dashboard & analytics

• get_dashboard · get_analytics (report: overview / pipeline / time_to_hire / sources / funnel_health / recruiters)

Import

• get_import_batch — status/progress of a candidate import batch.

Note: these tools call core-api (api.curriculo.me), which proxies the agent-graph flows to the internal Python service. The MCP never calls the Python service directly.

Security

• The raw token is never logged. Only the 16-char prefix (pat_<12>) ever appears in output.
• Credentials are stored locally at ~/.curriculo/credentials.json with file mode 0600 (parent dir 0700).
• All traffic goes over HTTPS to the configured API URL.
• Scope and expiry are enforced server-side; this client never makes trust decisions on the token.
• To revoke: https://ats.curriculo.me → Settings → Developers → Revoke. Or curriculo-mcp logout to wipe the local copy.

License

Proprietary. See LICENSE. This binary is licensed for use against the Curriculo ATS; the source is not publicly distributed.