AI agents & MCP

Connect MCP

Hosted server: https://verifyref.com/api/mcp

Create a key at Developer settings (rc_test_ sandbox — no emails, no credit debit — or rc_live_ production).

Cursor / mcp.json

{
  "mcpServers": {
    "verifyref": {
      "url": "https://verifyref.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rc_test_YOUR_KEY"
      }
    }
  }
}

Claude Code / Claude Desktop

{
  "mcpServers": {
    "verifyref": {
      "url": "https://verifyref.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rc_test_YOUR_KEY"
      }
    }
  }
}

Discovery: /.well-known/mcp/server-card.json · /llms.txt · /AGENTS.md · /openapi.yaml

Stdio bridge (@datalinc/verifyref-mcp)

If your host does not support remote Streamable HTTP MCP, use the npm stdio bridge. It proxies to the hosted server with your API key.

{
  "mcpServers": {
    "verifyref": {
      "command": "npx",
      "args": ["-y", "@datalinc/verifyref-mcp"],
      "env": {
        "VERIFYREF_API_KEY": "rc_test_YOUR_KEY"
      }
    }
  }
}

Or run VERIFYREF_API_KEY=rc_test_… npx @datalinc/verifyref-mcp. Prefer the remote URL when the host supports it.

Recommended workflow

1. get_account — note credit balance.
2. upload_candidate_resume — add resumes to the talent pool (free), or list_candidates if the pool is already filled.
3. match_candidates_to_job — paste a job description; get top fits with scores (free).
4. create_reference_check — pass candidateId (1 credit on live keys). Never invent IDs — only use ones returned by VerifyRef.
5. If credits are low: purchase_credits — Stripe MPP Shared Payment Token, or open the returned checkoutUrl.

Do not skip candidate consent; VerifyRef emails consent before contacting references. Video interviews and employee surveys are available via REST (not MCP tools today). Exit interviews are dashboard-only.

MCP tools

Example inputs

// MCP: match_candidates_to_job
{
  "jobDescription": "Senior React engineer, 5+ years TypeScript, remote AU…"
}

// REST equivalent
POST https://verifyref.com/api/v1/talent-pool/match
Authorization: Bearer rc_test_…
{ "jobDescription": "…" }

// MCP: create_reference_check
{
  "candidateId": "cand_…",
  "candidateName": "Jane Doe",
  "candidateEmail": "jane@example.com",
  "questionnaireId": "tmpl_…",
  "references": [
    { "name": "Alex Manager", "email": "alex@acme.com", "relationship": "Manager" }
  ]
}

Agentic payments

POST /api/v1/credits/purchase accepts packages 5 | 20 | 50 | 100. When STRIPE_PROFILE_ID is configured, agents receive an HTTP 402 MPP challenge for Shared Payment Tokens. Otherwise (or as fallback) a Stripe Checkout URL is returned for the user.

OAuth 2.1 for MCP (instead of pasting API keys) is on the roadmap — see /.well-known/oauth-protected-resource. Declared scopes today: talent_pool, checks, credits.

Troubleshooting

• 401 / invalid key — confirm the key is copied fully from Developer settings; sandbox keys start with rc_test_.
• 402 insufficient credits — call purchase_credits or buy a pack in Billing, then retry.
• No emails in sandbox — expected for rc_test_. Use rc_live_ only when ready for real delivery.
• Rate limits — 100 requests/minute per API key.
• Smoke-test locally with npm run test:agent -- rc_test_YOUR_KEY (see repo TESTING_AGENT.md).