CareerPilot
Searches job listings from Hacker News 'Who is hiring?' threads via the Algolia API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CareerPilot Search for remote Python jobs and save the best three."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CareerPilot ๐งญ
An AI job-hunt copilot built on the Model Context Protocol โ search live job boards, shortlist openings, track your application pipeline, and generate tailored resumes/cover letters, all from any MCP client (Claude Desktop, Claude Code, MCP Inspector).
Built as a learning project that deliberately exercises every major MCP concept in a real product.
Real data, no API keys
Source | What it is |
Remote job board, free public API | |
Remote job board, free public API | |
Hacker News "Who is hiring?" | Monthly hiring thread, via the free Algolia API |
Your shortlist, applications, and profile live in a local SQLite DB (~/.careerpilot/careerpilot.db).
Related MCP server: four-leaf-mcp
MCP feature map
MCP concept | Where it lives in this project | What it teaches |
Tools |
| Model-callable actions with typed schemas |
Resources |
| App data exposed as readable context |
Resource templates |
| Parameterized URIs |
Prompts |
| Reusable, server-defined prompt workflows |
Sampling |
| Server โ LLM inversion; server needs no API key |
Elicitation |
| Mid-tool-call user input |
Roots |
| Filesystem boundaries negotiated with the client |
Subscriptions | pipeline & watches emit | Push notifications to subscribed clients |
Logging & progress |
| Server โ client observability |
Background notifications |
| Server-initiated protocol traffic |
Streamable HTTP |
| The production transport |
Authorization | Bearer-token resource server ( | The MCP auth spec's resource-server side |
The client side |
| Handshake, tool loop, sampling/elicitation/roots handlers |
Quickstart
uv sync
# Interactive protocol playground (best way to learn):
uv run mcp dev src/careerpilot/server.py
# โ opens MCP Inspector in the browser; poke every tool/resource/prompt,
# and test sampling + elicitation from the Inspector UIClaude Code: this repo ships a .mcp.json, so just open the project and approve the server.
Claude Desktop: claude_desktop_config.json โ
{
"mcpServers": {
"careerpilot": {
"command": "uv",
"args": ["run", "--directory", "/Users/shwetarani/Developer/MCP_Project", "careerpilot"]
}
}
}Then try, in plain language:
"Search for remote python jobs, save the best three, and track that I applied to the first one." "Read my pipeline and tell me who I should follow up with." "Use the cover letter prompt for job 2."
Architecture
โโโโโโโโโโโโโโโโโโโโโโโ MCP (stdio โ later Streamable HTTP)
โ MCP client + LLM โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ (Claude Code, etc.) โ โ
โโโโโโโโโโโโฌโโโโโโโโโโโ โ
โ tools / resources / prompts sampling / elicitation / roots
โผ (server โ client callbacks)
โโโโโโโโโโโโโโโโโโโโโโโ
โ CareerPilot server โ src/careerpilot/server.py (FastMCP)
โ โโโ sources.py โ Remotive ยท RemoteOK ยท HN (httpx, concurrent)
โ โโโ db.py โ SQLite: saved_jobs ยท applications ยท profile
โโโโโโโโโโโโโโโโโโโโโโโWatched searches (stage 2)
you> watch this search: "python backend", remotive only
-> Watch #1 created ... baseline: 10 current listingsA background poller re-runs every watch (default: every 15 min, tune with
CAREERPILOT_POLL_SECONDS) and pushes resources/updated notifications to any
client subscribed to careerpilot://watches โ the server talks first, with no
request in flight. Review new finds in careerpilot://watches/{id}, then
mark_watch_reviewed.
Production transport: HTTP + auth (stage 3)
# Serve over Streamable HTTP with bearer-token auth
CAREERPILOT_TOKEN=$(openssl rand -hex 24) uv run careerpilot --http --port 8848
# MCP endpoint: http://127.0.0.1:8848/mcp (requests without the token get 401)auth.py implements the SDK's TokenVerifier โ the resource server role in
the MCP authorization spec (401 + WWW-Authenticate, protected-resource
metadata, scope checks). Swap StaticTokenVerifier for a JWT verifier against
a real OAuth 2.1 IdP without touching the rest of the server.
docker build -t careerpilot .
docker run -p 8848:8848 -v careerpilot-data:/data -e CAREERPILOT_TOKEN=... careerpilotWeb dashboard

careerpilot --http also serves a dashboard at / โ a "hiring file" view of your
pipeline styled as stamped paperwork: an action tray (follow-ups due, unreviewed watch
finds), the application drawer grouped in triage order, watch index cards, and one-click
"I applied" / "mark reviewed" / status changes. Same process, same SQLite, two front
doors: humans at /, LLMs at /mcp โ and edits made in the browser push
resources/updated notifications to connected MCP clients.
uv run careerpilot --http # dashboard: http://127.0.0.1:8848/When CAREERPILOT_TOKEN is set, the dashboard locks too: open
/?token=<your token> once and that browser stays unlocked (cookie);
the JSON API also accepts the same Authorization: Bearer header as /mcp.
The client side: your own MCP host (stage 4)
careerpilot-chat is a complete MCP host in ~250 lines (src/careerpilot/host.py) โ
what Claude Desktop does, made visible:
export ANTHROPIC_API_KEY=sk-ant-...
uv run careerpilot-chat # spawn local server (stdio)
uv run careerpilot-chat --url http://host:8848/mcp --token ... # remote server
uv run careerpilot-chat --list # capability dump (no API key needed)It negotiates capabilities, exposes the server's tools to Claude, runs the
agentic tool-call loop, answers the server's sampling requests by calling
the Anthropic API, surfaces elicitation at the terminal, grants roots (cwd),
and prints server logs and push notifications. /tools, /read <uri>,
/prompt <name> k=v, /quit inside the REPL.
Learning roadmap โ complete โ
Stage 1 โ Server fundamentals: tools, resources, templates, prompts, sampling, elicitation, roots, subscriptions, logging/progress over stdio
Stage 2 โ Watched searches: background poller pushes
resources/updatednotifications when new matching jobs appearStage 3 โ Production transport: Streamable HTTP, bearer-token auth (MCP resource-server pattern), Dockerfile
Stage 4 โ The client:
careerpilot-chat, a minimal MCP host on the Anthropic API โ handshake, tool-call loop, sampling/elicitation/roots handlers
Development
uv sync # install
uv run mcp dev src/careerpilot/server.py # inspector
uv run careerpilot # run over stdio directly
CAREERPILOT_DB=/tmp/test.db uv run careerpilot # throwaway database
# End-to-end protocol tests (spawn the real server, no mocks on the MCP layer)
uv run python tests/e2e_stdio_test.py # stage 1: every MCP feature over stdio
uv run python tests/stage2_watches_test.py # stage 2: poller + notifications
uv run python tests/stage3_http_test.py # stage 3: HTTP transport + 401/authAvailable Tools
14 toolscheck_watchesA
Re-run all watched searches right now and report newly-found jobs.
Inputs: no named parameters. Returns: result
delete_applicationA
Delete an application from the pipeline (asks the user to confirm first).
Inputs: app_id (required). Returns: result
find_resumeA
Locate the user's resume in folders the client has granted access to (MCP roots), and remember its path in the profile.
Inputs: no named parameters. Returns: result
list_due_follow_upsA
List follow-ups that are due today or overdue.
Inputs: no named parameters. Returns: result
mark_watch_reviewedA
Clear the 'new' flag on a watch's findings after you've reviewed them.
Inputs: watch_id (required). Returns: result
save_jobA
Save a job to the shortlist. Pass the fields from a search_jobs result, or enter a job found elsewhere manually (source='manual').
Inputs: title (required), url, salary, source, +4 more. Returns: result
schedule_follow_upC
Schedule a follow-up reminder for an application. Date format: YYYY-MM-DD.
Inputs: date (required), app_id (required), note. Returns: result
score_job_fitA
Score how well a saved job matches the user's profile/resume (0-10 with reasoning).
Demonstrates MCP sampling: this server sends a prompt to the CLIENT's LLM and uses the completion โ the server needs no API key of its own.
Inputs: job_id (required). Returns: result
search_jobsA
Search live job openings across free job boards.
Args: query: Keywords, e.g. "python backend" or "devops kubernetes". source: "remotive", "remoteok", "hn" (Hacker News Who is Hiring), or "all". limit_per_source: Max results per board (1-20).
Inputs: query (required), source, limit_per_source. Returns: result
set_profileC
Store a profile fact used by prompts and fit-scoring.
Useful fields: name, role, years_experience, skills, location, salary_expectation, resume_path.
Inputs: field (required), value (required). Returns: result
track_applicationB
Record that you applied to a saved job. Creates a pipeline entry with status 'applied'.
Inputs: job_id (required), notes. Returns: result
unwatchC
Delete a watched search.
Inputs: watch_id (required). Returns: result
update_applicationB
Update an application's status and/or notes.
Valid statuses: saved, applied, screening, interviewing, offer, accepted, rejected, withdrawn, ghosted.
Inputs: app_id (required), notes, status. Returns: result
watch_searchA
Create a watched search: CareerPilot re-runs it in the background and notifies subscribers of careerpilot://watches when NEW jobs are posted.
The current results become the baseline โ only jobs appearing later count as new.
Inputs: query (required), source. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 14 tools
Each tool has a clearly distinct purpose: searching jobs, managing watches, tracking applications, scheduling follow-ups, etc. There is no ambiguity between tools like 'watch_search' and 'check_watches' or 'list_due_follow_ups' and 'schedule_follow_up' as they handle different actions.
All tool names follow a consistent verb_noun pattern using underscores (e.g., search_jobs, save_job, track_application). Even 'unwatch' and 'set_profile' fit the convention. No mixing of styles or vague verbs.
14 tools is well-scoped for a career assistant covering job search, application tracking, watches, profile management, and fit scoring. Each tool serves a clear role without being excessive or insufficient.
The tool set covers core workflows: searching, saving, applying, tracking, scheduling, and scoring. Minor gaps exist, such as no tools to list saved jobs or list all applications, which an agent might need to navigate the pipeline programmatically.
Maintenance
Related MCP Connectors
Job application copilot: create and manage copilots, see matched jobs and track applications.
A job-search companion: tailor your CV to a role, score fit, fix ATS issues. Also via MCP.
Job application tracker for developers - AI agents write over MCP, you review in a dashboard.
Search Thousands of jobs, Thousands of companies. MCP for Claude, ChatGPT, Codex and Cursor.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI job search, resume builder, and career advice via MCP2MIT

four-leaf-mcpofficial
AlicenseNot gradedqualityCmaintenanceJob search assistant and interview prep inside any ai tool via MCP or public skill. Every tool you'll need for your job search in one product.10 npm8MIT- FlicenseAqualityDmaintenanceEnables searching job listings, tracking applications, managing resumes, and tailoring resumes to job posts, all locally via MCP.20-
- AlicenseNot gradedqualityDmaintenanceAI-powered job search and resume customization MCP server that automates job searching and tailors resumes for each role.MIT