> ## 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 サーバー
> intervyo.ai を Claude、Codex、Cursor などの MCP クライアントに接続し、評価の構築、候補者の追加、面接のスケジュール、結果の読み取りを自然な言葉で行います。
intervyo の **リモート MCP サーバー** を使うと、AI アシスタントが自然な言葉で
intervyo ワークスペースを操作できます — Interviewer、Role、Round の構築、候補者の
追加、Session のスケジュール、結果の読み取りまで。Streamable HTTP 上で Model
Context Protocol を話すため、MCP に対応したあらゆるクライアントが接続できます。
## エンドポイントと認証
| | |
| --------------- | -------------------------------------------------------- |
| **URL** | `https://www.intervyo.ai/api/mcp` |
| **Transport** | Streamable HTTP |
| **認証（オプション 1）** | `x-api-key: iv_live_…` — **Developer → API Keys** で作成します |
| **認証（オプション 2）** | `Authorization: Bearer …` — OAuth 2.1（対応するクライアント向け） |
API キーはアカウントの権限を保持します。パスワードと同様に扱い、
アシスタントが必要とする範囲のみにスコープを限定してください。
## クライアントを接続する
セットアップ方法を選んでください — それぞれ 1 分程度で完了します。
ブラウザの claude.ai と Claude Desktop アプリを **OAuth** で接続します。API キー不要。
Claude Code と Claude Desktop を `x-api-key` ヘッダーで接続します。
OpenAI Codex を `~/.codex/config.toml` で接続します（直接または `mcp-remote`）。
Cursor を `~/.cursor/mcp.json` で接続します。
### 接続をテストする
```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" }'
```
## アシスタントに専門知識を与える — Skill を追加する
MCP サーバーはアシスタントに **ツール** を与えます。**Skill** は、それらを正しい
順序と正しいフィールド値で使う *専門知識* を与えます。インストールしておけば、
*「シニアバックエンドの採用ループをセットアップして」* と言うだけで、アシスタントが
完全なプランを提案し、承認するとそれを構築します。**サーバーと一緒に追加してください。**
## アシスタントにできること
ツールは概念ごとにグループ化されています。
| 領域 | 代表的なツール | 役割 |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Interviewers** | `list_interviewers`、`create_interviewer`、`update_interviewer` | Round を実行する AI ペルソナを構築・再利用します |
| **AI Avatars** | `list_ai_avatars`、`create_ai_avatar` | Interviewer に音声を与えます（名前 + 性別 + 音声 + 言語、画像なし）。**まず一覧を表示し、Interviewer を作成する前にユーザーにアバターを選ばせます**；`ai_avatar_id` で **再利用** します — `create_ai_avatar` はユーザーが明示的に要求した場合のみ |
| **Roles** | `list_roles`、`create_role`、`update_role` | 採用・評価の対象を定義します |
| **Rounds** | `list_rounds`、`create_round`、`update_round` | Role のステップを追加し、それぞれを Interviewer に紐付けます |
| **Participants** | `create_participant`、`create_participant_with_resume`、`bulk_create_participants`、`list_participants` | 人を追加します（履歴書からスキルを自動抽出） |
| **Sessions** | `create_session`、`list_sessions`、`get_session` | 面接をスケジュールし、結果を読み取ります |
| **Knowledge base** | `retry_knowledge_base_file` | Role/Round に添付された参照ドキュメントを管理します |
| **Files** | `upload_file` | PDF（base64）をアップロード → 履歴書 / ナレッジベース用のホスト型 URL |
| **Coding & recordings** | `generate_coding_problem`、`execute_code`、`get_recording_url` | コーディング Round + 署名付き録画リンク |
完全かつ常に最新のカタログを得るには、`tools/list` を実行します（またはアシスタントに「ここで何ができる？」と尋ねます）。
## PDF のアップロード（履歴書とナレッジベース）
MCP はファイルを multipart で送信できないため、PDF は **base64** としてアップロードし、
**ホスト型 URL** を受け取ります:
1. **`upload_file`** を `{ filename, content_base64, purpose }`
（`purpose`:`resume` または `knowledge_base`）で呼び出します。`{ url }` を返します。
2. その `url` を使用します:
* `create_participant` の **`resume_url`** として（スキルを自動抽出）、または
* `create_role` の **`knowledge_base_links`** に。
PDF のみ。ファイルは約 10 MB 未満に保ってください（base64 はリクエストを約 33% 膨張させます）。
履歴書から候補者を追加する場合は、2 段階の手順を省略して
**`create_participant_with_resume`** を `{ name, email, resume_filename,
resume_base64 }` で呼び出します。PDF をアップロードし、得られた URL で参加者を
1 回の呼び出しで作成します — スキル/言語は引き続き自動抽出されます。
生の HTTP を使いたい場合は、`POST /api/v1/uploads` が同じ API キーを受け付け、
`multipart/form-data`（`file` フィールド）**または** JSON
`{ filename, content_base64 }` の **いずれか** をサポートします — どちらも `{ data: { url } }` を返します。
```bash theme={null}
# multipart (curl) — 履歴書 → URL、その URL で参加者を作成
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\"}"
```
## 安全性
* **読み取りツール** は自由に実行しても安全です。**作成/更新** ツールはワークスペースを
変更するため、承認する前にアシスタントの提案を確認してください。
* **破壊的な** ツール（削除）は明示的な `confirm: true` を要求するため、
アシスタントが誤って削除することはありません。
生の HTTP を使いたい場合は、すべての MCP ツールがドキュメント化された REST エンドポイントに対応しています。