Homerun logo homerun.co

Live

Homerun API and MCP server

Homerun's API cannot close a job, disqualify a candidate or send more than the confirmation email. Sign in to Homerun once in your own Cloud Browser, and your AI agent does the work there for you. The same tools work over MCP for agents and as a REST API for scripts.

Sign up free View as Markdown

Not affiliated with Homerun.

Homerun has no API for this. So we run one for you.

Homerun's own API, a GitHub MCP server and Cotlet compared
What you need Homerun's APIGitHub MCP serverCotlet
Closing jobs, disqualifying, candidate emails No Partly Yes, 14 tools
Acts as you, signed in 24/7 No No Yes, Cloud Browser
Fixed for you when Homerun changes N/A No Yes, tested every 6h
Runs with your laptop off N/A No Yes, hosted

Checked Oct 22, 2026. Sources: Homerun Public API documentation · Homerun Help: What can you do with the Homerun Public API? · Homerun Help: How to generate our public API key · Homerun pricing

Your own Cloud Browser, on 24/7. Sign in once. We keep it connected.

  1. 01Sign in to Homerun in your own Cloud Browser

  2. 02Connect it for your agents

  3. 03Cotlet keeps it signed in and working

How do I connect Homerun to Claude, ChatGPT or my code?

AI agents connect over MCP, scripts call the REST API. Both reach the same 14 tools with one API key.

For AI agents: MCP

Add Cotlet to your agent once. Homerun and every other app you connect show up as its tools.

  • Claude
  • ChatGPT
  • OpenClaw
  • Hermes
  • GrokBot
  • Cursor
  • n8n
  • Any MCP client
  1. 1

    Add Cotlet to your agent

    Claude Code
    claude mcp add --transport http cotlet \
  https://cotlet.dev/mcp/v1 \
  --header "Authorization: Bearer $COTLET_API_KEY"
    Cursor
    {
  "mcpServers": {
    "cotlet": {
      "url": "https://cotlet.dev/mcp/v1",
      "headers": {
        "Authorization": "Bearer ${COTLET_API_KEY}"
      }
    }
  }
}
    Codex
    # ~/.codex/config.toml
[mcp_servers.cotlet]
url = "https://cotlet.dev/mcp/v1"
bearer_token_env_var = "COTLET_API_KEY"

    Paste the snippet for your client. The same server and key serve every app you connect, so you do this once.

For scripts: REST API

Every tool is an endpoint under /api/v1/homerun with its own method and path, such as POST /api/v1/homerun/jobs/{job_id}/candidates/{candidate_id}/to-stage/move, with the same API key. Our open-source repo has ready scripts to start from.

REST API docs

What can the Homerun API and MCP server do?

14 tools on your own Homerun account. Agents call them as operations of the MCP tools homerun_read and homerun_write; scripts call each one at its own REST endpoint, with the same inputs and answers.

API reference
Homerun tools in Cotlet's MCP server and REST API
Tool What it does Access
list_jobs List your jobs with their state and visibility. read
get_job Read one job: its hiring stages, closing date and application form questions. read
list_candidates List the candidates of one job, filtered by stage, tag or status. read
get_candidate Read a candidate profile with answers, ratings, notes and messages. read
list_tags List the tags your company uses on candidates. read
list_disqualification_reasons List the reasons you can give when disqualifying a candidate. read
add_candidate_note Add an internal note to a candidate profile. write
add_candidate_tag Add a tag to a candidate, creating the tag if it does not exist. write
remove_candidate_tag Remove a tag from a candidate. write
move_candidate_to_stage Move a candidate to another hiring stage of the same job. writeasks first
move_candidate_to_job Move a candidate to another job. writeasks first
disqualify_candidate Disqualify a candidate with a reason and choose whether to tell them. writeasks first
send_candidate_email Send an email to one candidate through Homerun. writeasks first
set_job_visibility Make an active job public, private or closed. writeasks first

Scroll the table for all 14 tools.

Ask in plain words. Your agent does the rest.

All Homerun use cases

Is it safe to connect Homerun?

You sign in yourself in your own Cloud Browser, we never save your password, and anything that reaches your readers waits for your OK. The browser profile is encrypted in the EU. Independent scanners grade cotlet.dev A+.

Security overview

How much do the Homerun API and MCP server cost?

One price for both: a tool call costs the same over MCP or REST. Free 7-day trial with 2,000 credits, no card needed. Then one-time credit packs, no subscription, valid 12 months. Most calls use 25 credits, and your Cloud Browser uses 50 credits a day while Homerun is enabled for agents, so 20 calls a day come to 550 credits.

See full pricing
Cotlet credit packs: price, credits and calls at 25 credits each
Credits Price, one time Calls at 25 credits Per 1,000 credits
5,000 $29 200 $5.80
15,000 $79 600 $5.27
32,000 $149 1,280 $4.66
60,000 $249 2,400 $4.15

Only successful calls use credits; failed calls and timeouts cost nothing. At a balance of 0 calls pause, never a surprise charge. Authenticate with the Authorization: Bearer header.

Questions

Does Homerun have an API?

Homerun has a documented Public API, version 2, but no official MCP server (checked 22 Oct 2026). It is for paid plans, trials get no key, and an admin creates the key. It reads jobs and manages candidates, but it cannot create, edit, publish or close a job.

How do I get access?

Sign up free, open Homerun under Integrations in the console and press Request access. Your free trial starts with your account, no card needed.

Is the MCP server different from the API?

No, only the way in. Cotlet builds each integration as a REST API and puts an MCP server on top, so both have the same 14 tools, the same inputs and answers, one API key and one price. AI agents such as Claude, ChatGPT or Cursor use MCP; scripts, cron jobs and HTTP steps in n8n, Make or Zapier use the REST API.

What is the Cloud Browser?

Your own Chrome that Cotlet runs for you in the EU, around the clock. You open it from the console, sign in to Homerun yourself and press Enable for agents. Your agent's calls go through it, from its IP with its cookies, so Homerun sees the browser you signed in with. Password saving is off and the profile is stored encrypted with AES-256-GCM.

Can my agent act without asking me?

Not on anything that reaches other people: move_candidate_to_stage, move_candidate_to_job, disqualify_candidate, send_candidate_email, set_job_visibility wait for your OK by default. You can switch that off per tool for scheduled runs.

Do I need a paid Homerun plan or an API key?

No key. Homerun's own Public API is for paid plans only, trials are excluded, and only an admin can generate a key. Cotlet works in your own Homerun account instead, so what your agent can do follows your permissions in Homerun.

Can it create or edit a job post?

No. The tools read jobs and change their visibility between public, private and closed. Writing and publishing a job post stays in Homerun, as it does in the Public API, where jobs are read-only.

Does a candidate see why they were disqualified?

No. Homerun does not share the disqualification reason with the candidate. They hear only from an email, and disqualify_candidate sends one only when you set notify to email.

Should I use a Homerun MCP server from GitHub instead?

Pick one if you want the code on your own computer and do not mind the upkeep: you install it, sign it in and fix it when Homerun changes. Pick Cotlet if you want it hosted and kept working for you.

Can I use it in n8n, Make or Zapier?

Yes. Add https://cotlet.dev/mcp/v1 in n8n's MCP Client node, or call the REST endpoints from an HTTP step in Make or Zapier.

Who runs Cotlet?

Cotlet is run by Take Group, a Polish software company working since 2019. Take Group runs about 3,200 websites on its own systems and has its own DevOps team for infrastructure security. We built and used integrations like this inside the company for years before opening them as Cotlet.

Is Cotlet affiliated with Homerun?

No. Cotlet is independent and not affiliated with Homerun.

Give your agent access to Homerun.

Free 7-day trial with 2,000 credits, no card needed.

Sign up free