MCP Server

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 connectors (web + desktop)

claude.ai in the browser + the Claude Desktop app, via OAuth. No API key.

Claude with an API key

Claude Code and Claude Desktop using an x-api-key header.

Codex CLI

OpenAI Codex via ~/.codex/config.toml (direct or mcp-remote).

Cursor

Cursor via ~/.cursor/mcp.json.

Test your connection

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 Interview-Setup 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:

Call upload_file with { filename, content_base64, purpose } (purpose: resume or knowledge_base). It returns { url }.
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 } }.

# 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.

API Reference

Prefer raw HTTP? Every MCP tool maps to a documented REST endpoint.

Get Started

Concepts

Cookbook

Tutorials

Guides

MCP

Endpoint & authentication

Connect your client

Claude connectors (web + desktop)

Claude with an API key

Codex CLI

Cursor

Test your connection

Give the assistant expertise — add the Skill

★ The Interview-Setup Skill

What the assistant can do

Uploading PDFs (resumes & knowledge base)

Safety

API Reference

​Endpoint & authentication

​Connect your client

Claude connectors (web + desktop)

Claude with an API key

Codex CLI

Cursor

​Test your connection

​Give the assistant expertise — add the Skill

★ The Interview-Setup Skill

​What the assistant can do

​Uploading PDFs (resumes & knowledge base)

​Safety

API Reference

Endpoint & authentication

Connect your client

Test your connection

Give the assistant expertise — add the Skill

What the assistant can do

Uploading PDFs (resumes & knowledge base)

Safety