# 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](https://modelcontextprotocol.io) 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](https://hirehappy.io/docs/quickstart) 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

```bash
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.

| Permission       | Lets the app                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| Read             | Find, read, compare and export jobs, applications, candidates and scorecards                        |
| Can make changes | Also 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

| Tool                       |        | What it does                                                                                                                                                           |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_jobs`                | Read   | The organization's jobs, newest first                                                                                                                                  |
| `get_job`                  | Read   | A job with its pipeline (stages, with how many applications are in each) and the rubric applications are scored against                                                |
| `query_applications`       | Read   | Find, 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_applications`        | Read   | Applications, filtered, with their stage and headline score                                                                                                            |
| `get_application`          | Read   | One application in depth: where it stands, its scorecard with evidence, the candidate's answers and resume                                                             |
| `get_applications`         | Read   | Up to 25 applications in depth at once, for comparing a shortlist                                                                                                      |
| `export_applications`      | Read   | Every application matching the filters, written to a CSV or JSON file, for bulk work                                                                                   |
| `search_candidates`        | Read   | The organization's candidates, one per person across jobs                                                                                                              |
| `get_candidate`            | Read   | A candidate with their applications and the team's notes                                                                                                               |
| `move_application`         | Change | Move an application to another stage; the last stage hires                                                                                                             |
| `set_application_bookmark` | Change | Bookmark an application for the team, or take the bookmark off                                                                                                         |
| `give_feedback`            | Change | Your ratings and recommendation on an interview, call or assessment                                                                                                    |
| `add_note`                 | Change | A note on a candidate for the team, as you                                                                                                                             |
| `update_job_rubric`        | Change | Reword, reweight, add or remove the criteria AI scores a job's applications against                                                                                    |
| `set_stage_focus_areas`    | Change | Set 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.
