> ## Documentation Index
> Fetch the complete documentation index at: https://intervyo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect intervyo.ai to Claude, Codex, Cursor, and other MCP clients — build assessments, add candidates, schedule interviews, and read results in natural language.
The intervyo **remote MCP server** lets an AI assistant operate your intervyo
workspace in natural language — build Interviewers, Roles, and Rounds, add
candidates, schedule Sessions, and read results. It speaks the Model Context
Protocol over Streamable HTTP, so any MCP-capable client can connect.
## Endpoint & authentication
| | |
| ------------------- | ------------------------------------------------------------------- |
| **URL** | `https://www.intervyo.ai/api/mcp` |
| **Transport** | Streamable HTTP |
| **Auth (option 1)** | `x-api-key: iv_live_…` — create one under **Developer → API Keys** |
| **Auth (option 2)** | `Authorization: Bearer …` — OAuth 2.1 (for clients that support it) |
Your API key carries your account's permissions. Treat it like a password and
scope it to only what the assistant needs.
## Connect your client
Pick your setup path — each takes a minute.
claude.ai in the browser + the Claude Desktop app, via **OAuth**. No API key.
Claude Code and Claude Desktop using an `x-api-key` header.
OpenAI Codex via `~/.codex/config.toml` (direct or `mcp-remote`).
Cursor via `~/.cursor/mcp.json`.
### Test your connection
```bash theme={null}
curl -X POST https://www.intervyo.ai/api/mcp \
-H "x-api-key: iv_live_your_key" \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'
```
## Give the assistant expertise — add the Skill
The MCP server gives the assistant the **tools**; the **Skill** gives it the
*expertise* to use them in the right order with the right field values. With it
installed, *"set up a senior backend hiring loop"* becomes a complete proposed
plan the assistant builds on your approval. **Add it alongside the server.**
## What the assistant can do
Tools are grouped by concept.
| Area | Representative tools | What it does |
| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Interviewers** | `list_interviewers`, `create_interviewer`, `update_interviewer` | Build and reuse the AI personas that run Rounds |
| **AI Avatars** | `list_ai_avatars`, `create_ai_avatar` | Give an Interviewer a voice (name + gender + voice + language, no image). **List first and let the user choose an avatar before creating the interviewer**; **reuse** via `ai_avatar_id` — `create_ai_avatar` only on explicit user request |
| **Roles** | `list_roles`, `create_role`, `update_role` | Define what you're hiring/assessing for |
| **Rounds** | `list_rounds`, `create_round`, `update_round` | Add the steps of a Role and point each at an Interviewer |
| **Participants** | `create_participant`, `create_participant_with_resume`, `bulk_create_participants`, `list_participants` | Add people (skills auto-extract from resumes) |
| **Sessions** | `create_session`, `list_sessions`, `get_session` | Schedule interviews and read results |
| **Knowledge base** | `retry_knowledge_base_file` | Manage reference docs attached to Roles/Rounds |
| **Files** | `upload_file` | Upload a PDF (base64) → hosted URL for resumes / knowledge base |
| **Coding & recordings** | `generate_coding_problem`, `execute_code`, `get_recording_url` | Coding rounds + signed recording links |
Run `tools/list` (or just ask the assistant "what can you do here?") for the full,
always-current catalog.
## Uploading PDFs (resumes & knowledge base)
The MCP can't send a file as multipart, so PDFs are uploaded as **base64** and you
get back a **hosted URL**:
1. Call **`upload_file`** with `{ filename, content_base64, purpose }`
(`purpose`: `resume` or `knowledge_base`). It returns `{ url }`.
2. Use that `url`:
* as **`resume_url`** on `create_participant` (skills auto-extract), or
* in **`knowledge_base_links`** on `create_role`.
PDFs only; keep files under \~10 MB (base64 inflates the request \~33%).
Adding a candidate from a resume? Skip the two-step dance and call
**`create_participant_with_resume`** with `{ name, email, resume_filename,
resume_base64 }`. It uploads the PDF and creates the participant with the
resulting URL in one call — skills/languages still auto-extract.
Prefer raw HTTP? `POST /api/v1/uploads` accepts the same API key and supports
**either** `multipart/form-data` (a `file` field) **or** JSON
`{ filename, content_base64 }` — both return `{ data: { url } }`.
```bash theme={null}
# multipart (curl) — resume → URL, then create the participant with it
URL=$(curl -s -X POST "https://www.intervyo.ai/api/v1/uploads?accountSlug=$TEAM" \
-H "x-api-key: $API_KEY" \
-F "file=@jane-resume.pdf" -F "purpose=resume" | jq -r .data.url)
curl -X POST "https://www.intervyo.ai/api/v1/participants?accountSlug=$TEAM" \
-H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
-d "{\"name\":\"Jane\",\"email\":\"jane@example.com\",\"role_id\":\"$ROLE_ID\",\"resume_url\":\"$URL\"}"
```
## Safety
* **Read tools** are safe to run freely. **Create/update** tools change your
workspace — review what the assistant proposes before approving.
* **Destructive** tools (delete) require an explicit `confirm: true`, so an
assistant can't delete by accident.
Prefer raw HTTP? Every MCP tool maps to a documented REST endpoint.