# Homerun ATS MCP Server

MCP server that connects AI agents to [Homerun](https://www.homerun.co/) — an applicant tracking system. Enables AI-assisted candidate review: browse vacancies, inspect applications, and leave review notes.

Standalone server. No runtime dependency on the platform. Users add it like any remote MCP server.

## Tools

| Tool                | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `list_vacancies`    | List job openings with optional status filter and pagination                     |
| `get_vacancy`       | Get full vacancy details (description, stages, location, department)             |
| `list_applications` | Search/filter applications by vacancy, stage, hired status, disqualification     |
| `get_application`   | Get full application details (candidate profile, notes, files, question answers) |
| `add_note`          | Add a review note to an application                                              |

## Setup

### Get a Homerun API key

Homerun App → Integrations → API Keys. Assign scopes:

- `vacancies:read`
- `job-applications:read`
- `job-application-notes:read` (for notes in get_application)
- `job-application-notes:write` (for add_note)

API access requires the Homerun Plus plan.

### Run locally

```bash
pnpm -F @softcery/mcp-homerun dev
```

Starts on `http://localhost:8080`. The MCP endpoint is `/mcp`.

### Environment variables

| Variable             | Default   | Description                                                           |
| -------------------- | --------- | --------------------------------------------------------------------- |
| `PORT`               | `8080`    | Server port                                                           |
| `HOST`               | `0.0.0.0` | Bind address                                                          |
| `SESSION_TIMEOUT_MS` | `1800000` | Session expiry (30 min)                                               |
| `ALLOWED_HOSTS`      | —         | Comma-separated allowed Host header values (DNS rebinding protection) |

## Connect

### From the platform

Admin UI → Agent → Integrations → Add Server:

- **URL:** `https://<deployed-host>/mcp`
- **API Key:** your Homerun API key

### From Claude Desktop

```json
{
  "mcpServers": {
    "homerun": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <HOMERUN_API_KEY>"
      }
    }
  }
}
```

### From any MCP client

Send an `initialize` request to `POST /mcp` with your Homerun API key as a Bearer token in the `Authorization` header. The server creates a stateful session — subsequent requests use the `mcp-session-id` header.

## Auth model

No server-level auth. The Bearer token from the client's `Authorization` header is used directly as the Homerun API key. Each user's key has its own rate limit (60 req/min).

## Development

```bash
pnpm -F @softcery/mcp-homerun test    # run tests
pnpm -F @softcery/mcp-homerun lint    # tsc + oxlint + knip
pnpm -F @softcery/mcp-homerun build   # production build
```

## Docker

```bash
docker build -f mcp-servers/homerun/Dockerfile -t mcp-homerun .
docker run -p 8080:8080 mcp-homerun
```