What it is
TheBetterHire MCP is a remote Model Context Protocol connector for the TheBetterHire interview intelligence platform. Once added, your AI assistant can call the same APIs theTheBetterHire dashboard uses — to schedule interviews, run AI screens, score resumes against a JD, retrieve scorecards, and produce debrief reports.
The connector mirrors the public REST API at /api/public/v1. All calls are made with the authenticated user's organization scope; the assistant cannot see other organizations.
What you can do
- Match resumes to a JD — drag a job description and up to 10 resumes into a chat, get a ranked, evidence-backed list with strengths and concerns per candidate.
- Run an AI screen — fire off a 15-30 minute AI-led voice or video screening. The candidate gets an email with a join link.
- Schedule a full AI interview — 45, 60, or 90 minute structured interview against a competency rubric, conducted by TheBetterHire's brain agent.
- Schedule a human interview — calendar invite goes out, the recording bot joins Google Meet / Zoom / Teams automatically and analyzes afterward.
- Inspect results — pull scorecards, transcripts, time-coded evidence audio, and PDF reports on demand.
- Compare and decide — rank 2-5 candidates side by side; aggregate every round into a single debrief with a hire / maybe / reject call.
- Subscribe via webhooks — receive HMAC-signed event notifications when interviews are transcribed, analyzed, or failed.
Connecting from Claude.ai
Claude.ai handles OAuth automatically. You only need the connector URL.
- In Claude.ai, open Settings → Connectors (or the connector picker in a conversation).
- Choose Add custom connector.
- Paste the connector URL:
https://mcp.thebetterhire.ai/mcp
- Complete the OAuth handshake when Claude opensTheBetterHire's sign-in page in a new tab. Approve the requested scopes (
mcp:read,mcp:write). - Start a chat and prompt as you normally would. The connector's tools become available immediately.
Connecting from ChatGPT
ChatGPT supports custom MCP servers in developer mode (text tools work today; widget rendering is platform-dependent).
- Open ChatGPT settings and enable Developer mode if you haven't already.
- Under Apps, choose Add custom MCP server.
- Paste the connector URL above and complete the OAuth prompt.
- The tools become available in any conversation where the connector is enabled.
Some inline rendering features (rich widgets, SVG scorecards) are not yet supported on every client. The connector falls back to plain text in those cases.
Example prompts
These are real prompts that work end-to-end. Use them as a jumping-off point.
Rank a stack of resumes against a JD
I need to hire a Senior Backend Engineer. Here is the JD: [paste JD]. Score these 5 resumes against it: [paste each resume].
The connector calls match_resumes (or create_upload_session if you'd rather drop files into a browser tab) and returns a ranked list with each candidate's score, top strengths, and biggest concern.
Send a candidate to an AI screening
Set up an AI screening for raj@example.com for the Senior Backend Engineer role. The JD is: [paste]. The resume is: [paste].
The connector calls trigger_screening. The candidate receives an email with a join link; the AI agent conducts the call. Results are available a few minutes after the candidate finishes.
Get the scorecard for a completed interview
What did Priya Sharma's interview show? Pull the scorecard.
The connector calls search_candidates → list_interviews → get_interview, then renders the scorecard. Ask for a clip from a specific evidence timestamp and it will fetch the audio URL.
Compare three candidates and pick one
Compare these three candidates head-to-head and tell me who I should hire and why.
Calls compare_candidates with all three candidate IDs, summarizes the strengths, and returns a hire/reject recommendation with rationale.
Tool reference
The connector exposes 25 tools grouped below. The assistant picks the right one based on your prompt — you don't need to memorize them.
Interview operations
| Tool | Description |
|---|---|
submit_interview | Submit an existing meeting URL or recording URL for transcription, scoring, and a full analysis. |
get_interview | Fetch the scorecard, recommendation, evidence, and transcript for a specific interview. |
list_interviews | Browse interviews with filters by status, candidate email, role, and date range. |
get_scorecard_image | Render a visual scorecard graphic with overall score and competency heatmap. |
get_interview_audio | Get a time-limited audio URL for the interview recording. Pair with evidence timestamps to seek to a specific moment. |
download_interview_report | Get a public download link for the interview analysis PDF. |
delete_interview | Permanently delete an interview and its recording (GDPR Article 17). |
Resume matching
| Tool | Description |
|---|---|
match_resumes | Score and rank up to 10 resumes against a job description. |
create_upload_session | Generate an upload URL where Marcus can drag in a JD and up to 10 resumes from his desktop. |
get_upload_results | Check whether files have been uploaded to a session and get a token to feed into match_resumes. |
Scheduling
| Tool | Description |
|---|---|
trigger_screening | Send a candidate a link or phone call for a short AI-led screening. |
schedule_brain_interview | Book a 45/60/90-minute structured interview where TheBetterHire's brain agent IS the interviewer. Requires a job_role_id with a competency rubric. |
schedule_interview | Book a human-led interview on Google Meet/Zoom/Teams. The recording bot joins automatically and analyzes afterward. |
Candidates & debriefs
| Tool | Description |
|---|---|
search_candidates | Find candidates by name or email. |
get_candidate_debrief | Aggregate all interviews for a candidate into one hire/no-hire summary. |
get_debrief_by_email | Same as above but resolves the candidate by email when you don't have their candidate_id handy. |
download_debrief_report | Get a download link for the cross-interview debrief PDF. |
Comparison
| Tool | Description |
|---|---|
compare_candidates | Rank 2-5 candidates side by side across competencies. |
download_comparison_report | Get a download link for the side-by-side comparison PDF. |
Webhooks
| Tool | Description |
|---|---|
register_webhook | Subscribe an HTTPS endpoint to interview events (transcribed, analyzed, failed). Returns a signing secret shown once. |
list_webhooks | List all registered webhooks for the organization. |
delete_webhook | Remove a webhook. It stops receiving events immediately. |
get_webhook_deliveries | Show the last N delivery attempts for a webhook with status code, latency, and error message. |
Account
| Tool | Description |
|---|---|
get_balance | Show the credit wallet balance, bundle price for this org, and per-action extra rates (screen, interview, round). |
submit_feedback | Record a 1-5 rating and a comment about a specific tool or response. |
Troubleshooting
OAuth opens, then fails or hangs.
Check that you're signed in to TheBetterHire on the same browser session. If the popup is being blocked, allow popups for Claude.ai or ChatGPT. If it still fails, remove the connector and re-add it.
The assistant says it has no tools available.
The connector may have lost its session. Toggle it off and back on in your assistant's connector settings. If a specific tool is missing, the underlying account may not have the corresponding feature enabled — contact support.
“I need a job_role_id.”
Brain interviews require an existing job role with a competency rubric. Create one in the dashboard at /job-roles, then ask the assistant to look it up: "list my job roles". You can also pull the job_role_id from any prior interview in get_interview.
Candidate didn't receive the screening invite.
Check spam folders first; the sender is noreply@thebetterhire.ai. Ask the assistant to look up the interview by ID — the response includes a delivery status. You can re-trigger by calling trigger_screening again with the same arguments.
Audio link expired.
Audio URLs are signed and time-limited. Just ask the assistant to fetch the audio again — it will get a fresh link via get_interview_audio.
Webhook isn't firing.
Use get_webhook_deliveries to inspect the last attempts, status codes, and error messages. Common causes: HTTPS endpoint returning non-2xx, wrong event type, or signing-secret mismatch.
Support
Questions, bug reports, or feature requests: support@thebetterhire.ai.
Legal: Privacy Policy · Terms of Service