What is MCP?
The Model Context Protocol (MCP) is an open standard that lets AI assistants securely connect to external tools. Instead of copy-pasting data between your assessment platform and your AI assistant, MCP lets the assistant call Adaface directly - so you can ask it to look up candidates, check scores, or send assessments, in plain language.
Adaface's MCP server exposes your account's assessment workflows as tools, authenticated with your Adaface API key. No integration code required - just configure your MCP client to connect to the server.
What your assistant can do
Read-only (default access level):
List your tests and their details
Check a candidate's assessment status and score
List all assessments for a candidate by email
Page through historical interviews
Check your credit balance and usage
View test requests and their status
Search Adaface's public test library
List reusable self-serve share links (onelinks)
Read & write (opt-in):
Send an assessment to a candidate
Resend an invite or send a reminder
Cancel a pending invite
Shortlist or archive a candidate
Create or toggle a self-serve share link
Buy a ready-to-go test or request a custom-built one
Choosing an access level
Read-only mode lets your assistant look things up but never take action - safe for exploring your data with zero risk. Read & write mode lets it act on your behalf, including sending real assessment invites to candidates and spending credits. Some actions (like a sent invite email) can't be undone, so only enable read & write if you want the assistant to actually execute tasks, not just answer questions.
You can change your access level anytime from your Adaface dashboard.
Setup
Step 1 : Enable MCP
Go to Dashboard → Settings → Integrations → MCP.
Choose an access level: Read only or Read & write.
Click Enable MCP.
Step 2 : Get your API key
Go to Dashboard → Settings → API Keys.
Click Generate new API key.
Copy it - you won't be able to see it again.
Now connect your MCP client using this key. Instructions below are for Claude Code; other MCP clients follow a similar pattern, but exact config fields vary - check your client's own MCP documentation for the correct syntax.
Connecting Claude Code
Open (or create) .mcp.json in your project, and add:
{
"mcpServers": {
"adaface": {
"type": "http",
"url": "https://api.adaface.com/app/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_ADAFACE_API_KEY"
}
}
}
}Replace YOUR_ADAFACE_API_KEY with the key from Step 2. Restart Claude Code, and approve the server when prompted ("Use this MCP server").
Run /mcp to confirm - you should see Adaface listed as connected, with the available tools shown based on your selected access level (more if you enabled read & write).
Example workflow 1 - Invite candidates to a test
Prompt: "List my Adaface tests"
Claude calls list_tests and shows you test names and IDs.
Prompt: "Invite janedoe@example.com and alexsmith@example.com to the JavaScript (Coding): Data Structures Test"
Claude finds the test automatically, then calls send_test for each candidate - no test ID needed, just describe the test by name. You'll get back an interview ID and invite link for each.
(Requires Read & write access.)
Example workflow 2 - Check a candidate's score
Prompt: "What is the status of Sarah Chen (sarahchen@example.com) in SAP SuccessFactors test?"
Claude looks up her interview via list_candidates, then calls get_test_status to pull the score, status, and scorecard link.
Other things you can try
You're not limited to these two workflows - ask naturally and Claude will pick the right tool:
"How many credits do I have left?"
"Search the test library for a SQL assessment"
"Shortlist janedoe@example.com's interview"
"Cancel alexsmith@example.com's pending invite"
"List my share links for the Data Structures test"
If something doesn't work as expected, see Troubleshooting below.
Troubleshooting
Message | Cause | Fix |
| Missing or wrong bearer token | Re-check the key in |
| MCP toggle is off | Enable MCP under Settings → Integrations → MCP |
MCP server shows "Skipped" in | Missing | Add |
Rate limit errors | More than 60 requests/minute | Slow down or batch fewer requests |
A write action didn't run | Account is in read-only mode | Switch to Read & write in Settings → Integrations → MCP |