HireFrog MCP 🐸

Connect your AI assistant to your HireFrog job search.

Search jobs, understand why opportunities match your background, save jobs to your HireFrog queue, and continue your application workflow at HireFrog.

What this is

HireFrog MCP is a small, public Model Context Protocol server that gives an MCP-compatible AI client (Claude, and any other client that speaks Streamable HTTP MCP) a narrow, authenticated window into your own HireFrog account — the same account and data you already use at hirefrog.co.

It is a thin adapter, not a second copy of HireFrog. Every tool call reads or writes through the same authenticated backend the HireFrog web app uses (Supabase Postgres protected by Row Level Security, and HireFrog's existing authenticated roleflow-ai service for the one tool that needs AI). No matching logic, resume-generation logic, or database access lives in this repository.

Related MCP server: JobDataLake MCP Server

What it can do (V1)

Every response includes a link back to hirefrog.co so you can pick up the workflow there.

What it intentionally does not do

This is a deliberately lightweight V1 — an on-ramp to HireFrog, not a replacement for it. It does not: generate a tailored resume, generate a cover letter or application answers, submit applications, edit your master resume or profile, touch billing/subscriptions, or run bulk/automated actions. Where one of these would be useful, a tool response links you to the right place in HireFrog to finish the job. See docs/FUTURE_TOOLS.md for what's technically ready to build on this later, and why it isn't in V1 yet.

It also never runs a new HireFrog search against job boards — search_jobs searches jobs HireFrog has already found for you. Run a new search at hirefrog.co/app/search.

Architecture

See docs/ARCHITECTURE.md for the full request path and module layout. In short:

MCP client → this server (Streamable HTTP, stateless)
           → Supabase (same Postgres + Row Level Security + Auth
              HireFrog's own web app uses), scoped to your own token
           → HireFrog's existing roleflow-ai Edge Function for AI analysis

This server never holds a database credential, an AI provider key, or a Stripe/TheirStack key — it only ever acts as you, using the same authorization rules the web app already enforces.

Authentication

Every tool call requires Authorization: Bearer <token>, where the token is resolved to your HireFrog identity by verifying it against Supabase Auth — the exact same check every HireFrog Edge Function performs. No tool ever accepts a user/account/profile id as an argument; identity comes only from this token.

Current limitation: HireFrog doesn't yet have a dedicated long-lived API token for this. For now, the token is your HireFrog session's Supabase access token, which expires after about an hour. Until a proper token (OAuth or a HireFrog-issued personal access token) ships, you'll need to refresh it periodically — see docs/SECURITY.md for detail and the reasoning.

Local development

git clone https://github.com/HireFrog/hirefrog-mcp.git
cd hirefrog-mcp
npm install
cp .env.example .env   # fill in HIREFROG_SUPABASE_URL / HIREFROG_SUPABASE_ANON_KEY
npm run dev             # starts on http://127.0.0.1:3000

Then verify it's up:

curl http://127.0.0.1:3000/health

Before opening a PR, run everything CI runs:

npm run lint
npm run typecheck
npm test
npm run build

Connecting an MCP client

Point any MCP client that supports the Streamable HTTP transport at:

http://127.0.0.1:3000/mcp     (local)
https://mcp.hirefrog.co/mcp   (hosted, once deployed — see below)

with header Authorization: Bearer <your HireFrog access token>. Exact configuration is client-specific — consult your client's docs for how it adds a custom remote MCP server with a bearer token. This README doesn't claim compatibility with any specific client beyond what the MCP Streamable HTTP spec requires.

Deployment

This server has no state of its own and is a normal Node HTTP service — a Dockerfile is included. It's designed to eventually run at https://mcp.hirefrog.co/mcp, but no hosting/DNS for that exists yet; this repo doesn't assume it does. To run it yourself:

docker build -t hirefrog-mcp .
docker run -p 3000:3000 --env-file .env hirefrog-mcp

In production, set NODE_ENV=production, use a real HIREFROG_SUPABASE_URL, and if binding to 0.0.0.0 behind a reverse proxy, set MCP_ALLOWED_HOSTS (see .env.example and docs/SECURITY.md).

Security

See docs/SECURITY.md for the full threat model. In short: no tool ever accepts a user/account id from the client, every request rides HireFrog's own Row Level Security via your own token, the one AI-backed tool goes through HireFrog's existing metered/authenticated service (this server can't bypass your usage limits even if it wanted to), and no secret or full bearer token is ever logged or returned in a response.

Found a real vulnerability? Please report it privately rather than filing a public issue — see contact info on hirefrog.co.

Contributing

Issues and PRs are welcome. Since this repo intentionally stays a thin adapter, changes that would move HireFrog business logic, matching/scoring algorithms, or database access into this repository will be redirected back toward exposing a small endpoint on HireFrog's own backend instead — see docs/ARCHITECTURE.md for why. Please run npm run lint && npm run typecheck && npm test && npm run build before opening a PR.

Links

• HireFrog: hirefrog.co — don't have an account yet? Sign up to get the full HireFrog experience this server is a doorway into.

• HireFrog on GitHub: github.com/HireFrog

License

MIT — see LICENSE.