Before retrieving report data, your agent must establish which candidate it's acting on behalf of. The candidate proves their identity through an email OTP flow:
- Agent calls
request_candidate_verification(email)→ Checkr emails a 6-digit code to the candidate. - Candidate provides the code to your agent through chat.
- Agent calls
verify_candidate_otp(email, code)→ session is locked to that candidate.
Once a candidate is identified, the session is locked to them for its entire lifetime.
Once a candidate is identified, call get_report() (no parameters needed). Returns the candidate's latest background check report including:
- Overall status and result
- Per-screening breakdown (status, result, type)
- Dispute/exception info if applicable
- Candidate portal link
A session begins when your agent connects with a valid bearer token. The server returns an Mcp-Session-Id that identifies the session.
| Rule | Detail |
|---|---|
| Session lifetime | 1 hour |
| Identity binding | Immutable — once account, email, or candidate is set, it cannot change within the session |
| One candidate per session | A session is locked to a single candidate for its entire lifetime |
| OTP send limit | 3 attempts per session |
| OTP verify limit | 3 attempts per session |
| Ownership enforcement | Your agent can only access candidates and reports belonging to your Checkr account |
Send an HTTP DELETE to the MCP endpoint with the Mcp-Session-Id header. The server closes the connection and rejects any further requests on that session ID with 404 Not Found.
If no DELETE is sent, sessions expire automatically after 1 hour.
- The previous session expired or was terminated
- An unrecoverable error occurs (e.g., repeated OTP failures)
Important: Do not reuse sessions across different end users. Each user interaction should start a fresh session to prevent data leakage between candidates.
When interacting with Checkr's MCP tools, your agent should:
- Present all returned data. Don't omit or over-summarize screening results. Candidates need the full picture.
- Never fabricate report data. Only relay what the MCP returns.
- Handle errors clearly. Relay error messages to the user (e.g., "candidate does not belong to your account") without retrying in a loop.
- One candidate per conversation. If the user asks about a different candidate, explain that the current session is locked and a new conversation is needed.