FreeApply technical documentation

Architecture

FreeApply is an MCP server (Model Context Protocol, the standard way AI apps connect to tools). It is a local Node.js process with no dependencies that your AI app starts and talks to over stdio; there is no website you log in to. It has three parts:

• Your AI app (Claude Desktop, Claude Code, Cursor, VS Code in Copilot agent mode, or Windsurf) does the reasoning and the browsing on your own plan: it reads postings, decides what fits and fills in forms in your signed-in browser session.
• FreeApply, on your computer: the MCP server with 22 tools, the signed procedures your AI follows, a local database in ~/.freeapply, and the dashboard at http://127.0.0.1:7878, reachable only from your computer. In Claude Code it also installs three skills (setup, apply, replies) that point to those procedures.
• Our server (www.mybotsai.com): this website, the downloads, signed updates, the sponsored-card pack and the anonymous statistics you choose to share. It never receives your résumé or applications unless you join the Recruiter Talent Pool.

A run, step by step

1. Check: the AI calls freeapply_status, which reports whether the Terms are accepted, setup is complete and the signed workflow verifies, then loads the apply procedure with freeapply_workflow.
2. Search: it searches the sources you chose. Company career pages on Greenhouse, Lever and Ashby are read through their public APIs, which saves tokens.
3. Score and claim: each job gets a fit score from 0 to 100. freeapply_check_duplicate must run before freeapply_add_job claims it; posted pay below your floor is recorded as skipped.
4. Fill in: facts come only from your settings, résumé and saved answers. Cover letters and free-text answers go through freeapply_check_text.
5. Pace and submit: freeapply_throttle must clear with the job's ID right before each submit; freeapply_update_job refuses the status "applied" without that clearance.
6. Hand over: CAPTCHAs, new accounts, passwords and unanswered questions go to the dashboard's Needs you list, and the AI moves on.

Guardrails

The rules are enforced by the tools, not only written in a prompt: an AI can be talked out of an instruction, but not out of a tool that refuses the call.

• Signed workflow: the procedures, server instructions and hard limits ship signed with our release key (Ed25519). If anything changes them, the tools lock until the official copy is restored, and an update installs only when its signature verifies.
• Truthfulness check: cover letters and answers that claim tools, numbers or years of experience your résumé and settings don't support are refused; the AI has to ask you instead.
• Pace and limits: a per-minute pace check before every submit, an optional daily cap, and a site that signs you out or shows its own daily limit is paused while the others continue.
• Hands off your accounts: FreeApply never asks for, types or stores a password, never creates accounts and never solves CAPTCHAs.

Data and network

Everything personal lives in ~/.freeapply: résumé, settings, the jobs database and recorded emails. FreeApply contacts our server only for these:

• Updates: about once a day it checks for newer signed instructions; the request carries only the app version.
• Sponsored cards: a few times a day it downloads the current card pack (unchanged packs aren't downloaded again) and picks a card on your computer. Nothing about you is sent.
• Sharing you allow, set in Settings → Data sharing, where you can preview what would be sent and delete what was shared:

The legal detail is in the Privacy Policy.

Why not ChatGPT yet

ChatGPT connects only to MCP servers hosted on the internet, and FreeApply runs locally so your job search stays on your computer. A hosted version for ChatGPT is planned, with its own sign-in and privacy terms.

What the installer does

Claude Desktop needs nothing else: it runs the .mcpb extension with its own built-in Node.js. Claude may note that the extension has no code-signing certificate (those are paid); the package is signed with our own release key instead (how to check).

For the other apps, the one-line installer needs Node.js 22.13 or newer. install.ps1 (Windows) and install.sh (macOS, Linux) check for Node.js and run install.mjs, which downloads the package, checks its signature and SHA-256, unpacks it into your user folder and asks before adding FreeApply to each app it finds. It edits only each app's MCP settings file and keeps a backup next to it:

• Claude Code: runs claude mcp add -s user freeapply … and installs the skills in ~/.claude/skills.
• Cursor: adds freeapply to ~/.cursor/mcp.json.
• VS Code: adds freeapply to your user mcp.json (use it from Copilot Chat in agent mode).
• Windsurf: adds freeapply to ~/.codeium/windsurf/mcp_config.json.
• Claude Desktop: adds freeapply to claude_desktop_config.json. Quit Claude completely and reopen it afterwards. If you also installed the extension, keep only one of the two.

Claude Code plugin

Instead of the installer, Claude Code can install FreeApply as a plugin from the GitHub repository:

/plugin marketplace add FreeApply/freeapply
/plugin install freeapply@freeapply

Manual setup

Any app that runs local MCP servers over stdio can use FreeApply. Download and unpack freeapply.mcpb (it is a ZIP file), then add a server that runs Node.js on src/main.js:

{
  "mcpServers": {
    "freeapply": { "command": "node", "args": ["/path/to/freeapply/src/main.js"] }
  }
}

FreeApply is listed in the official MCP Registry as io.github.FreeApply/freeapply.

Uninstall

Claude Desktop: Settings → Extensions → FreeApply → Uninstall. For the other apps, run the installer with the uninstall option:

$env:FREEAPPLY_ARGS='--uninstall'; irm https://www.mybotsai.com/appserver/install.ps1 | iex

curl -fsSL https://www.mybotsai.com/appserver/install.sh | bash -s -- --uninstall

This removes FreeApply from your apps and deletes the program files. Your data in ~/.freeapply stays until you delete that folder.

Verify a download

The current package is (loading). Its signature file (.sig.json) holds the package's SHA-256, signed with an Ed25519 key whose private half never leaves our offline machine. The public key ships inside FreeApply (keys/release.pub) and inside install.mjs; latest.json lists the current version, file name and SHA-256.

SHA-256: see latest.json · signing key: –

To compare the checksum on Windows:

Get-FileHash .\freeapply.mcpb -Algorithm SHA256

On macOS or Linux:

shasum -a 256 freeapply.mcpb

The result must equal the SHA-256 above. The installer does this and the signature check for you, and the app verifies every update the same way: a download that doesn't match is refused.

Source code

The source is on GitHub under the MIT License (the FreeApply name and logo aren't covered). Release notes for every version are on the News page. Bug reports and questions: mybotsai@gmail.com.