# Curriculo ATS MCP Server Documentation

> Connect your Curriculo ATS to Claude, Cursor, and any MCP-compatible AI client. The Curriculo ATS MCP server is a remote, hosted server at https://mcp.curriculo.me/mcp with nothing to install. Authenticate once with OAuth 2.1 or a Personal Access Token, and the client gains 25 tools that read and act on your hiring data in real time.

**Source:** https://curriculo.me/docs/mcp/ (Curriculo ATS)

| Property | Value |
|---|---|
| Endpoint | https://mcp.curriculo.me/mcp |
| Transport | Streamable HTTP |
| Auth | OAuth 2.1 + Personal Access Token (PAT) |
| Scopes | ats:read, ats:write |
| Tools | 25 |

The Curriculo ATS MCP server is a remote, hosted server, nothing to install or run locally. Point any MCP client at the endpoint, authenticate once, and the client gains a set of tools that read and act on your hiring data in real time.

## Quickstart

Use this endpoint everywhere: `https://mcp.curriculo.me/mcp`

The fastest path is Claude's one-click connector flow:

1. Open Claude, then Settings, then Connectors.
2. Click Add custom connector and paste the server URL above.
3. Complete the OAuth sign-in when prompted. Claude connects to your organization.
4. Start a chat and ask, for example, "What's sitting in each stage of my open roles?"

New here? Follow the step-by-step [tutorial: run your ATS in Claude](https://curriculo.me/mcp/run-your-ats-in-claude/).

## Connect a client

The server speaks Streamable HTTP and supports both interactive OAuth and a Personal Access Token via an `Authorization: Bearer` header.

### Claude
In Claude (web or desktop), go to Settings, Connectors, Add custom connector, then enter:
```
https://mcp.curriculo.me/mcp
```
Click Add, complete the OAuth sign-in, then open the connector to enable the specific tools you want Claude to use.

### Claude Code
Add the server with a single command (OAuth opens in your browser via `/mcp`):
```
claude mcp add --transport http curriculo https://mcp.curriculo.me/mcp
```
Or pass a Personal Access Token directly with a header:
```
claude mcp add --transport http curriculo https://mcp.curriculo.me/mcp \
  --header "Authorization: Bearer YOUR_CURRICULO_PAT"
```

### Cursor
Open Cursor Settings, Tools & MCP, New MCP Server, and add this to `mcp.json`:
```json
{
  "mcpServers": {
    "curriculo": {
      "url": "https://mcp.curriculo.me/mcp"
    }
  }
}
```

### VS Code / other
Any client without native remote-MCP support can use the `mcp-remote` bridge:
```json
{
  "mcpServers": {
    "curriculo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.curriculo.me/mcp"]
    }
  }
}
```

## Authentication

Two ways to authenticate. Both resolve to a user in one organization with scoped permissions.

### OAuth 2.1 (recommended)
Interactive clients (Claude, Cursor) use OAuth with dynamic client registration. You sign in to Curriculo, approve the connection, and the client stores a short-lived token it refreshes automatically.

### Personal Access Token (PAT)
For CLI or headless setups, generate a token in the ATS and send it as a Bearer header:

1. Sign in at ats.curriculo.me.
2. Go to Settings, API & Integrations, Personal Access Tokens.
3. Create a token, choose its scopes, and copy it (shown once).
4. Pass it as `Authorization: Bearer <token>`.

### Scopes
- **ats:read**: List and read jobs, applicants, inbox, interviews, analytics.
- **ats:write**: Create and change data: move stages, send email, schedule interviews, update jobs.

Call the `whoami` tool to confirm the authenticated user, organization, auth method, and granted scopes.

## Tools reference (25 tools)

Read tools never change data. Write tools create or modify records and may trigger emails, calendar events, or automations.

### Jobs (4)
- `list_jobs` (read): List jobs in your organization, newest-updated first. Params: status, page, limit.
- `get_job` (read): Full details of one job by UUID, including funnel stages and applicant count. Params: jobId (required).
- `create_job` (write): Create a job posting with default funnel stages. Only title is required; opens in draft. Params: title (required), description, location, type, headcount, must_have_skills, preferred_skills, salary_min/max, salary_currency.
- `update_job_status` (write): Change a job's status (DRAFT / OPEN / PAUSED / CLOSED / ARCHIVED). Params: jobId, status (both required).

### Applicants (8)
- `list_applicants` (read): List applicants, optionally scoped to a job, with starred / rejected / archived filters. Params: jobId, starred, rejected, archived, page, limit.
- `get_applicant` (read): Full applicant detail: funnel stage, job link, notes, activity history. Params: applicantId (required).
- `search_candidates` (read): Semantic search across all candidates. Params: query (required), jobId, timestamp, page, limit.
- `move_applicant_stage` (write): Move an applicant to another funnel stage. Fires funnel automations. Params: applicantId, funnelId (required), reason.
- `add_applicant_note` (write): Add a note to an applicant. Params: applicantId, content (required), noteType, decisionFlag, roundName.
- `get_applicant_resume_text` (read): Parsed resume text and structured data. Params: applicantId (required).
- `get_applicant_evaluation` (read): AI agent-graph evaluation: suitability score, AI tags, summary, gap status. Params: applicantId (required).
- `reprocess_resume` (write): Re-run the resume pipeline (parse + evaluation + graph ingest). Params: applicantId (required).

### Inbox & email (5)
- `get_applicant_email_thread` (read): Full email thread for an applicant. Params: applicantId (required).
- `list_inbox_emails` (read): List inbound emails in the org inbox. Params: jobId, status, search, page, limit.
- `get_inbox_stats` (read): Inbox summary stats: unread counts and totals. Params: none.
- `reply_to_applicant_email` (write): Reply to an applicant, threading onto the latest inbound email. Requires connected Gmail. Params: applicantId, body (required), subject.
- `send_bulk_email` (write): Send an email to one or more applicants by id. Requires connected Gmail. Params: applicantIds, subject, messageBody (all required).

### Interviews (2)
- `list_interviews` (read): List interviews. Params: jobId, applicantId, status, type, dateFrom, dateTo, page, limit.
- `schedule_interview` (write): Schedule an interview, mint feedback links, and (with Gmail) sync a calendar event and email everyone. Params: applicantId, jobId, title, scheduledStart, scheduledEnd (required), plus type, location, meetingProvider, participantIds, externalInterviewers, timezone, instructions.

### Analytics (2)
- `get_analytics` (read): Org analytics overview: total applicants, period change, pipeline-by-stage, top jobs, source mix. Defaults to last 30 days. Params: dateFrom, dateTo.
- `get_dashboard` (read): Inbox plus per-job funnel breakdown of active applicants. Params: none.

### Automations & imports (3)
- `list_job_automations` (read): List funnel automations configured for a job. Params: jobId (required).
- `get_automation_executions` (read): Execution history for a single automation, paginated. Params: automationId (required), page, limit.
- `get_import_batch` (read): Status of a candidate import batch: progress, per-file status, errors. Params: batchId (required).

### Account (1)
- `whoami` (read): Return the authenticated user, organization, auth method, and granted scopes. Params: none.

## Example prompts

- "Show me what's sitting in each stage of my open roles, and flag anything stalled."
- "Find senior React engineers with team-lead experience and summarize the top five."
- "Move Priya to Second Interview and draft a reply asking for her availability next week."
- "Schedule a 45-minute video interview with this candidate on Thursday 2pm ET and add a Google Meet link."
- "How did applicant volume change vs last month, and which job is converting best?"

Write tools have real side effects (sending email, changing pipelines, closing jobs). Keep tool approvals on for write actions until you trust a workflow, and grant only ats:read if you just want analysis.

## FAQ & troubleshooting

### Do I need to install or host anything?
No. The server is fully hosted at https://mcp.curriculo.me/mcp. Point your client at the URL and authenticate.

### Which clients are supported?
Any MCP client that supports remote servers over Streamable HTTP: Claude (web/desktop), Claude Code, Cursor, VS Code, and others. Clients without native remote support can use the `mcp-remote` bridge.

### My tools show "Needs login" or won't connect.
Re-run the OAuth flow (in Claude Code, type `/mcp`; in Cursor, click Needs login). If you use a PAT, confirm the header is exactly `Authorization: Bearer <token>` and the token has not been revoked or expired.

### An email or interview tool returns an error.
Email and calendar tools (reply_to_applicant_email, send_bulk_email, the email side of schedule_interview) require an active Gmail connection on the organization. Connect Gmail in the ATS, then retry.

### How do I limit what the AI can do?
Issue a token with only ats:read for analysis-only access, and use your client's per-tool permission settings to disable specific write tools.

### Which organization does it act on?
The one tied to your token. Call whoami to confirm the user, organization, and scopes at any time.

## Security

- **Scoped access.** Every token is bound to one user and organization and carries explicit ats:read / ats:write scopes.
- **Least privilege.** Grant the narrowest scope that does the job; prefer read-only tokens for analysis.
- **Revoke anytime.** Personal Access Tokens can be revoked in Settings, API & Integrations; OAuth connections can be removed from your client's connector settings.
- **Transport security.** All traffic is HTTPS over Streamable HTTP. Never paste a token into untrusted clients or share it in plain text.

---
*Canonical HTML version: https://curriculo.me/docs/mcp/*