Skip to main content
VirtualInterview.ai
Docs menu

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 Authorization header. The server URL is https://hiring.virtualinterview.ai/api/mcp.

Connect

  1. Add the server to your MCP client with the URL above and the header Authorization: Bearer followed by your key.
  2. The client sends initialize. The server answers with its protocol version and a tools capability.
  3. The client sends tools/list and gets one tool per operation the key may call.
  4. 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:

initialize
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" }'
Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "virtualinterview-hiring", "version": "1.0.0" }
  }
}
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": 2, "method": "tools/list" }'
tools/call
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" } }
  }'
Response
{
  "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

MCP errors
What went wrongWhat you get
Missing or invalid keyHTTP 401 with { "error": "Invalid API key" }.
Too many requestsHTTP 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 toolJSON-RPC error -32602.
Unknown methodJSON-RPC error -32601.
Body is not a JSON-RPC requestJSON-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.

Was this page clear?