# HireLab Screener — Personal MCP Connector

Lets *your* Claude read from *your* HireLab Screener ATS. Read-only and safe: it
logs in as a service account and calls your existing owner-scoped API, so all
your tenant-isolation rules apply. Claude can search and read; it cannot edit or
delete.

## What Claude can do (15 tools)

**Read (always on)**
| Tool | What it answers |
|---|---|
| search_candidates | semantic search — "senior PLC engineer in Pune under 20 LPA" |
| search_database | filtered search by company/location/CTC |
| list_mandates | your open roles |
| get_pipeline | candidates in a mandate + stage |
| get_candidate | one candidate's full profile |
| get_today_tasks | your action items |
| get_overview | business snapshot |

**Write / Actions (on when `MCP_ALLOW_WRITES=true`, the default)**
| Tool | What it does | Confirmation |
|---|---|---|
| add_candidate | add a new candidate to a mandate | normal |
| move_candidate_stage | move a candidate's stage | normal |
| update_candidate | edit candidate fields (CTC, notice, feedback…) | Claude confirms (edits data) |
| schedule_interview | schedule an interview round | normal |
| add_tags | tag a candidate | normal |
| create_task | add a to-do to the Command Center | normal |
| create_reminder | create a follow-up reminder | normal |
| send_candidate_email | **send a real email** to a candidate | Claude confirms (sends email) |

You can now just tell Claude what to do — e.g. *"Add Ravi Kumar (ABB, 18 LPA, Pune) to the L&T PLC mandate and set a reminder to call him tomorrow."*

### Safety
- Every action goes through your ATS's owner-scoped API, so Claude only ever touches your company's data.
- Write tools carry MCP annotations, so Claude surfaces/asks before edits and email sends.
- No delete tools are exposed — deletions stay in the app.
- Flip `MCP_ALLOW_WRITES=false` in Render anytime to instantly go back to read-only.

## One-time setup

### 1. Create a service account in your ATS
Make a normal ATS user (e.g. username `claude-mcp`) with a strong password. Using
a dedicated account means you can revoke MCP access anytime without touching your
own login. It must belong to your company so it sees your data.

### 2. Deploy this folder as a NEW Render service
- Put this folder in a Git repo (or a subfolder) and create a **new** Render Web
  Service pointing at it (it is separate from your ATS service).
- Render will use `render.yaml` (build: install requirements, start: python mcp_server.py).
- In the new service's **Environment**, set:
  - `ATS_BASE_URL`  = your ATS URL, e.g. `https://hirelabscreener.onrender.com` (no trailing slash)
  - `ATS_USERNAME`  = `claude-mcp`
  - `ATS_PASSWORD`  = that account's password
  - `MCP_SECRET`    = a long random string (e.g. 30+ characters). Keep it private.
  - `MCP_ALLOW_WRITES` = `true` to allow actions (add/update/email), or `false` for read-only. Default `true`.
- Deploy. Check `https://<your-mcp-service>.onrender.com/health` returns `{"status":"ok"}`.

### 3. Add it to Claude
- Claude.ai → Settings → Connectors → **Add custom connector**.
- Name: `HireLab Screener`
- URL: `https://<your-mcp-service>.onrender.com/mcp`   ← just `/mcp`, no secret in the URL.
- Leave OAuth Client ID / Secret **blank**. Click **Add**.
- Claude will open a small **"Connect HireLab Screener"** page — enter your `MCP_SECRET`
  there once and click Authorize. Claude is now connected.
- In a chat, open the connectors menu, enable it, and ask: *"List my open mandates."*

Why the secret page? claude.ai's web connector flow requires an OAuth sign-in
step even for personal servers, so the connector performs a lightweight OAuth
handshake. Your `MCP_SECRET` is the one-time "sign in". Tokens last 30 days;
changing `MCP_SECRET` instantly revokes access.

## Security notes
- The MCP endpoint is hidden behind your secret path; without it, requests get 404.
- Tools are read-only. To add write actions later (with confirmation), extend
  TOOLS in `mcp_server.py`.
- Rotate access by changing `MCP_SECRET` (update the connector URL) or by
  disabling the service account in your ATS.
- Free Render services sleep when idle; the first call after a nap may take ~30s
  to wake. Upgrade the plan if you want it always-on.