MCP server
The MCP server lets an AI agent call the hiring API as tools. It speaks JSON-RPC over HTTP POST at /api/mcp on the hiring portal, takes the same API keys as the REST API, and lists only the tools the key’s scopes allow. Human-only decisions stay behind the decisions:human scope.
How-to · Last checked against the product on
What you need
- An API key created under Settings → Developers, with the scopes for the tools the agent should have. See API quickstart.
- An MCP client that can send JSON-RPC over HTTP with an
Authorizationheader. The server URL ishttps://hiring.virtualinterview.ai/api/mcp.
Connect
- Add the server to your MCP client with the URL above and the header
Authorization: Bearerfollowed by your key. - The client sends
initialize. The server answers with its protocol version and atoolscapability. - The client sends
tools/listand gets one tool per operation the key may call. - The agent calls a tool with
tools/call, passing the tool name and its arguments.
You can run the same exchange by hand to check a key:
curl -X POST https://hiring.virtualinterview.ai/api/mcp \
-H "Authorization: Bearer $VI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }'{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-03-26",
"capabilities": { "tools": {} },
"serverInfo": { "name": "virtualinterview-hiring", "version": "1.0.0" }
}
}curl -X POST https://hiring.virtualinterview.ai/api/mcp \
-H "Authorization: Bearer $VI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'curl -X POST https://hiring.virtualinterview.ai/api/mcp \
-H "Authorization: Bearer $VI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": { "name": "listApplications", "arguments": { "stage": "DEBRIEF" } }
}'{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [ { "type": "text", "text": "{\"applications\":[…]}" } ]
}
}The server answers POST only. A GET returns 405.
Tools
Each tool is one operation from the API reference. The tool name is the operation id, such as listApplications or draftOffer, and its input schema is the operation’s request fields, path parameters included. A tool returns the same JSON as the REST call, as a text item.
tools/list leaves out any tool the key’s scopes do not cover, so an agent never sees a tool it cannot use. Jobs, candidates, webhook subscriptions and bulk invitations are REST-only.
Errors
| What went wrong | What you get |
|---|---|
| Missing or invalid key | HTTP 401 with { "error": "Invalid API key" }. |
| Too many requests | HTTP 429; the key’s rate limit is shared with the REST API. |
| A tool refused the call (scope, validation, not found, conflict) | A normal result with isError: true and the reason as text. |
| Unknown tool | JSON-RPC error -32602. |
| Unknown method | JSON-RPC error -32601. |
| Body is not a JSON-RPC request | JSON-RPC error -32600. |
Agents and human decisions
An agent should run on a key without decisions:human. It can then read applications, file scorecards, request schedules, draft offers and move candidates through the non-final stages, while rejecting, offering, hiring and approving proposals are refused. A person makes those calls from the portal, or from a key they control. See Authentication and scopes.