Docs

Search the docs

Guides, sections and API endpoints

AI

Connect AI apps (MCP)

Add HireHappy to Claude, ChatGPT, Cursor or any MCP client, so it can work with your jobs and candidates as a member of your hiring team.

HireHappy runs an MCP server, the open standard AI apps use to connect to other software. Connect it, and your AI app can answer questions about your jobs, applicants and scores, and keep the pipeline moving, in plain words:

  • "Who are the strongest Backend Engineer applicants with open source work?"
  • "Compare the three best on system design, with evidence."
  • "Export the whole pipeline as a spreadsheet."
  • "Move Jonah to Interview and tell the team why."

It's for people working in their AI app. For your own systems and scripts, use the API instead.

The server URL

Text
https://api.hirehappy.io/mcp

Any app that supports remote MCP servers over HTTP, with OAuth sign-in, can connect. There's nothing to install and no key to copy.

Connecting

When you add the server, your app sends you to HireHappy to sign in. There you pick one organization for the app, and whether it can make changes or only read. Approve, and you're back in your app, connected.

Claude

In Claude (web or desktop), go to Settings → Connectors → Add custom connector, name it HireHappy, and paste the server URL. On Team and Enterprise plans, an owner adds it for the organization first.

Claude Code

Shell
claude mcp add --transport http hirehappy https://api.hirehappy.io/mcp

Then run /mcp in Claude Code, pick hirehappy, and sign in.

ChatGPT

In ChatGPT's settings, under Apps & Connectors, add a custom connector with the server URL. Custom connectors need developer mode on some plans; ChatGPT's help explains the steps for yours.

Cursor

Add it to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

JSON
{
  "mcpServers": {
    "hirehappy": { "url": "https://api.hirehappy.io/mcp" }
  }
}

VS Code

Add it to .vscode/mcp.json, then start it from the file or the MCP view:

JSON
{
  "servers": {
    "hirehappy": { "type": "http", "url": "https://api.hirehappy.io/mcp" }
  }
}

Other apps

Point them at the server URL. The server is its own OAuth 2.1 authorization server, with discovery (RFC 9728 and RFC 8414), dynamic client registration (RFC 7591) and PKCE, so apps that follow the MCP spec set themselves up.

What it can see and do

The app acts as you, in the one organization you picked: it sees exactly what you can in HireHappy, and nothing more. If you leave the organization, it loses access too.

PermissionLets the app
ReadFind, read, compare and export jobs, applications, candidates and scorecards
Can make changesAlso move applications, bookmark them, give feedback, add notes, and change rubrics and focus areas

Apps that ask before running tools (Claude does, by default) show each change before it's made. Changes show in HireHappy as made by you.

To disconnect an app, open Settings → AI apps in HireHappy. It loses access at once.

Tools

ToolWhat it does
list_jobsReadThe organization's jobs, newest first
get_jobReadA job with its pipeline (stages, with how many applications are in each) and the rubric applications are scored against
query_applicationsReadFind, screen and rank applications on the server, by score, any rubric criterion, GitHub, resume text, education, stage or status, returning only the fields asked for
list_applicationsReadApplications, filtered, with their stage and headline score
get_applicationReadOne application in depth: where it stands, its scorecard with evidence, the candidate's answers and resume
get_applicationsReadUp to 25 applications in depth at once, for comparing a shortlist
export_applicationsReadEvery application matching the filters, written to a CSV or JSON file, for bulk work
search_candidatesReadThe organization's candidates, one per person across jobs
get_candidateReadA candidate with their applications and the team's notes
move_applicationChangeMove an application to another stage; the last stage hires
set_application_bookmarkChangeBookmark an application for the team, or take the bookmark off
give_feedbackChangeYour ratings and recommendation on an interview, call or assessment
add_noteChangeA note on a candidate for the team, as you
update_job_rubricChangeReword, reweight, add or remove the criteria AI scores a job's applications against
set_stage_focus_areasChangeSet what the team rates in a stage's interviews, calls or assessments

The server keeps results lean, filtering and ranking itself rather than handing your AI app everything to read, so answers come faster and stay within the app's limits on big jobs.

Troubleshooting

  • The app can't connect. Check the URL ends in /mcp, and that the app supports remote (HTTP) MCP servers with OAuth. Some only run local servers.
  • It says it isn't allowed to make a change. You connected it read-only. Disconnect it under Settings → AI apps and connect again, allowing changes.
  • It's looking at the wrong organization. An app connects to one organization. Disconnect it and connect again, picking the other one.