# Lever MCP Server

A remote [Model Context Protocol](https://modelcontextprotocol.io/) server exposing the Lever ATS API as tools callable from Claude. Built on **Express + GCP Cloud Run**. v3 target auth: the server is its **own OAuth 2.1 Authorization Server** brokering **Google Workspace** sign-in restricted to `@samba.tv` (no Auth0 in the login path — mirrors the MSCI MCP).

> **Canonical architecture spec:** [`system-design.md`](./system-design.md) (404 lines, 13 sections — current state, target architecture, multi-tenant auth model, MCP spec 2025-11-25 compliance, operational runbook, decision log).
>
> **Refactor tracking:** [ATF-476](https://sambatv.atlassian.net/browse/ATF-476) on Jira · [Confluence hub](https://sambatv.atlassian.net/wiki/spaces/ATF/pages/14838136852).

---

## What this is

When a Samba employee asks Claude to "check the candidate status for X" or "submit my interview feedback for Y," Claude calls this MCP server. The server validates the user's OAuth token, resolves their authenticated email to a Lever user record (multi-tenant `perform_as` model — see system-design.md §4), and forwards the request to the Lever REST API with proper audit attribution.

> **Status (as of 2026-05-27):** Single-tenant mode. All write operations attribute to `LEVER_DEFAULT_USER_ID` (Sid). Per-user `perform_as` resolution lands in [M3b](./CLAUDE.md#v3-refactor-in-progress) — JWT validation and email logging are live today, but the email→Lever user ID resolver is not yet wired. Read operations are unaffected.

**Live endpoint:** `https://lever-mcp-201626763325.us-central1.run.app/mcp`

**Tool count:** 17 live tools across search, candidate management, applications/files, interviews, requisitions, reference data, user lookup, and 5 action-enum tools (notes, feedback, archive, stages, requisitions). See [Tools](#tools) below.

---

## Architecture

```
Claude (MCP client)
   │ treats this server as the OAuth 2.1 AS; self-registers via DCR (/register),
   │ runs PKCE S256 against our /authorize + /token
   ▼
Lever MCP Server (this repo, GCP Cloud Run us-central1) — acts as the AS
   │ /authorize → redirects to Google (hd=samba.tv, prompt=select_account)
   │ /oauth/google/callback → validates Google ID token (RS256, iss, hd==samba.tv),
   │   mints an opaque Bearer token ↔ the user's email
   │ every /mcp request: validate opaque token → resolve email
   │ → resolve email → Lever user ID (perform-as-resolver, TTL cache) — **M3b, pending**
   │ → attach resolved user ID as `perform_as` on writes
   ▼
Lever ATS REST API (api.lever.co/v1)
```

**Stack:**

| Layer | Choice |
|---|---|
| Language | TypeScript (Node.js 20+) |
| HTTP server | Express 4.21 |
| MCP SDK | `@modelcontextprotocol/sdk` 1.29 |
| MCP transport | Streamable HTTP |
| MCP-Protocol-Version | `2025-06-18` (target: `2025-11-25` per M1.5) |
| JWT validation | `jose` 6 |
| Schema validation | `zod` 3 |
| Deploy target | GCP Cloud Run, region `us-central1` |
| Auth | OAuth 2.1 — self-hosted Google OAuth broker (Google Workspace IdP, `@samba.tv`) |

See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for request-flow diagrams + auth-chain failure recovery procedures.

---

## Prerequisites

- Node.js 20+ and npm
- [GCP account](https://cloud.google.com/) with Cloud Run enabled (for deploy)
- [Lever API key](https://hire.lever.co/settings/integrations) with scopes for: opportunities, postings, users, stages, archive_reasons, feedback_templates, requisitions, feedback (read + write), interviews (write), notes (write), webhooks (read + write)
- A Google OAuth 2.0 Web Client (for the auth broker) — self-serve setup in [`docs/google-oauth-setup.md`](./docs/google-oauth-setup.md)

---

## Install

```bash
git clone https://github.com/the-sid-dani/lever-mcp-server.git
cd lever-mcp-server
npm install
```

---

## Local development

```bash
# Run local dev server (tsx watch, port 8080)
npm run dev

# Type check (no emit)
npm run type-check

# Run tests (vitest)
npm test

# Watch mode
npm run test:watch

# Format
npm run format

# Lint + autofix
npm run lint:fix
```

Set the required env vars locally (see [`.env.example`](./.env.example) for the full list):

```bash
export LEVER_API_KEY=<your-key>
export LEVER_DEFAULT_USER_ID=<your-lever-user-uuid>
export NODE_ENV=development
```

For the OAuth broker path during local dev, also set `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `MCP_PUBLIC_URL`, and `ALLOWED_HOSTED_DOMAIN=samba.tv` (see [`docs/google-oauth-setup.md`](./docs/google-oauth-setup.md)). To bypass OAuth locally and use single-tenant fallback (server reads `LEVER_DEFAULT_USER_ID` for `perform_as`), set `OAUTH_ENABLED=false`.

---

## Deploy

```bash
# Build + push container + deploy revision via Cloud Build + Cloud Run
npm run deploy
```

Behind the scenes: `gcloud builds submit --config cloudbuild.yaml`. Production environment variables are managed via Cloud Run service config (no `.env` file in production).

Rollback to a previous revision:

```bash
gcloud run revisions list --service lever-mcp --region us-central1
gcloud run services update-traffic lever-mcp \
  --to-revisions=<previous-revision>=100 \
  --region us-central1
```

---

## Connect from Claude

Once the server is deployed and the Google OAuth client is configured, register the MCP server in Claude.ai (or Claude Code) using the standard remote MCP flow. Claude discovers this server as the OAuth AS, self-registers via DCR, and runs the PKCE auth code flow automatically. First connect prompts a Google login at `@samba.tv` and consents to the requested scopes.

Local dev / debugging:

```bash
# Install the MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector against local dev server (OAUTH_ENABLED=false recommended)
npx @modelcontextprotocol/inspector
# Enter: http://localhost:8080/mcp
```

---

## Tools

17 tools registered (post-consolidation). See [system-design.md §8](./system-design.md#tool-surface-v1--v3) for the canonical inventory.

**Search & discovery (4)**

`lever_advanced_search`, `lever_search_candidates`, `lever_find_postings_by_owner`, `lever_list_open_roles`

**Candidate management (2)**

`lever_get_candidate`, `lever_update_candidate`

**Application / files / emails (3)**

`lever_list_applications`, `lever_list_files`, `lever_list_emails`

**Interview (2)**

`lever_manage_interview`, `lever_get_interview_insights`

**User lookup (1)**

`lever_get_users`

**Notes (1) — `lever_notes(action)`**

- `action="list"` — fetch all notes on a candidate
- `action="get"` — fetch one note by id
- `action="add"` — create a new note (single-tenant — attributed via `LEVER_DEFAULT_USER_ID`)

**Feedback (1) — `lever_feedback(action)`**

- `action="list_templates"` — discover available feedback forms org-wide
- `action="list"` — all feedback on a candidate
- `action="get"` — one feedback form by id
- `action="submit"` — submit a filled-out form (single-tenant — uses `fieldValues[]` write-shape per Lever API)

**Archive (1) — `lever_archive(action)`**

- `action="list_reasons"` — discover valid archive reason IDs
- `action="archive"` — archive a candidate
- `action="search"` — query archived candidates by posting / date range / recruiter / reason

**Stages (1) — `lever_stages(action)`**

- `action="list"` — fetch all pipeline stages
- `action="history"` — stage-change history for a specific opportunity

**Requisitions (1) — `lever_requisitions(action)`**

- `action="list"` — fetch requisitions with optional filters (status, code, date, confidentiality)
- `action="get"` — fetch full details for one requisition by Lever UUID or external code (smart lookup)

### Why action-enum tools?

Reduces schema-token overhead ~30-40% vs the prior 26-tool registry (consolidated 2026-05-27, commits `17951ea`...`71d999c`). Same-resource operations share one tool, dispatched by `action` enum. Background: `continuum/research/code-mode-vs-many-tools/findings.md`.

### Out of scope (future batches)

- M5 write tools (`lever_feedback(action="update")`) — blocked on M3b multi-tenant perform_as resolver (fed by the Google OAuth broker; no IT dependency)
- M6 webhook tools (`lever_list_webhooks`, `lever_register_webhook`, `lever_delete_webhook`) — same blocker

---

## Project structure

```
src/
├── server.ts                 # Cloud Run entry, Express setup, MCP transport wiring
├── tools.ts                  # registerAllTools + 4 tool registrations (search, candidates, postings)
├── additional-tools.ts       # 11 tool registrations including 5 consolidated action-enum tools (split into src/tools/ in v3 M3a)
├── interview-tools.ts        # 2 interview-specific tool registrations
├── lever/
│   └── client.ts             # LeverClient — REST wrapper, rate limit, pagination
├── auth/
│   ├── middleware.ts         # JWT validation, OAUTH_ENABLED toggle, Cloud Run IAM fallback
│   ├── metadata.ts           # OAuth 2.0 Protected Resource Metadata endpoint
│   ├── constants.ts
│   ├── types.ts
│   └── index.ts
├── types/lever.ts            # Lever API response type definitions
└── utils/stage-helpers.ts

test-fixtures/lever-api/      # Probe captures (2026-05-22) + synthetic fixtures for M4 tests
system-design.md              # Canonical architecture spec (v3 refactor)
ARCHITECTURE.md               # Request-flow diagrams + failure recovery
scaffold-spec.yaml            # Spec used to publish Confluence + create Jira Stories
```

---

## Testing

```bash
npm test         # vitest run (full suite)
npm run test:watch
```

Current coverage focuses on auth middleware (`src/auth/__tests__/middleware.test.ts`). Tool-level test coverage lands in v3 M4 — fixtures already captured in `test-fixtures/lever-api/`.

---

## Known limitations

1. **`perform_as` is required on every Lever write** — every POST/PUT in Lever v1 requires `perform_as=<user-uuid>`. v3 multi-tenant resolver (M3b) derives this from the authenticated user's email → Lever user lookup. v1/v2 single-tenant mode uses `LEVER_DEFAULT_USER_ID` env var.
2. **MCP session state is per-Cloud-Run-container memory** — revision swaps drop active sessions; clients reconnect transparently. Acceptable for single-region single-revision deploy. See system-design.md §7 "MCP session state" for context.
3. **No webhook ingestion sink** — v3 M6 ships registration tools only (3 tools). Persisting inbound webhook events is a separate future project once a real consumer use case exists.
4. **MCP-Protocol-Version pinned at `2025-06-18`** — v3 M1.5 bumps to `2025-11-25` after a compliance audit (RFC 8707 resource parameter, RFC 9207 iss validation, PKCE S256 hard-MUST, Client ID Metadata Documents support).

---

## Contributing

This is `the-sid-dani`'s personal repo. The v3 refactor is tracked at [ATF-476](https://sambatv.atlassian.net/browse/ATF-476). Each milestone has its own Story (ATF-477 through ATF-490). PRs welcome with reference to the relevant Story.

```bash
git checkout -b refactor/<feature>
# make changes...
npm run type-check && npm test
git commit -m "feat(...): short description"
# Push, open PR against `main`
```

---

## License

MIT (see [LICENSE](./LICENSE) if present).

---

## References

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Lever ATS Developer Documentation](https://hire.lever.co/developer/documentation)
- [Google Identity — OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect)
- [GCP Cloud Run](https://cloud.google.com/run/docs)
- [`system-design.md`](./system-design.md) — canonical v3 design
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — request-flow + failure recovery
- [`CLAUDE.md`](./CLAUDE.md) — Claude Code guidance for this codebase