@formacv/mcp

@formacv/mcp — Official Model Context Protocol server for FormaCV

Drive AI-powered CV formatting, anonymization, AI tailoring, and ATS push-back from Claude Desktop, Cursor, and your own AI agents — using the Model Context Protocol.

What this is

FormaCV gives staffing teams AI CV formatting and polished resume formatting without bouncing files through manual Word cleanup. Agencies connect their ATS, upload unlimited branded CV templates, and deliver client-ready collateral in roughly a minute. The @formacv/mcp MCP server extends that workflow to whichever AI agent stack you prefer: recruiters can orchestrate tailor → anonymize → push-back sequences straight from conversational tools rather than juggling separate tabs.

Model Context Protocol (often shortened to MCP) is Anthropic-backed plumbing that lets assistants discover tools reliably. Installing this MCP server means Claude, Cursor Copilots, or bespoke automation can call eight well-documented primitives — format_cv, tailor_cv, anonymize_cv, push_to_ats, plus batching, introspection helpers, and asynchronous job polling — with JSON contracts identical to FormaCV’s HTTPS API.

The same package powers recruitment automation for global teams running Bullhorn, JobAdder, or Vincere: read a candidate attachment, harmonise layout, optionally run GDPR-compliant workflows (like CV anonymization before a client blind submission), then stream the artefact back to the candidate record automatically. Keywords your compliance team cares about map to product reality: deterministic audit logs on anonymization flows, configurable retention, AES-256 at rest / TLS in motion, isolated infrastructure per tenant, optional on-premises deployment — all surfaced on FormaCV Security.

Quickstart (try without an API key)

• Ensure Node.js 18+ is available (the MCP transport launches via npx).
• Export demo-friendly defaults before starting your AI assistant:

export FORMACV_API_KEY=demo
export FORMACV_SERVER_URL=https://demo.formacv.ai

No sales call is required for this step — the MCP server answers with deterministic sample payloads that mirror production JSON envelopes. Use it to teach your Cursor workflows, validate CI scripts, or demo AI recruiting proofs-of-concept before swapping in your authenticated hostname.

Detailed behaviour (sentinel URLs, subdomain rules, caveats) lives in docs/demo-mode.md.

Install

Ad-hoc invocation (recommended for MCP hosts):

npx -y @formacv/mcp

Project-local dependency:

npm install @formacv/mcp
pnpm add @formacv/mcp

Bins resolve to the same STDIO executable your AI client shells out to. Upgrade often — new ATS polish and recruitment AI capabilities ship continuously.

Environment variables recap

Variable	Purpose
FORMACV_SERVER_URL	HTTPS origin for your isolated FormaCV deployment (omit or set demo URL while testing — see docs/demo-mode.md).
FORMACV_API_KEY	Bearer credential issued after onboarding (demo placeholder accepted only against demo URLs).

Configure your AI client

Pick the snippet that matches how your team ships copilots. Each JSON file lives under examples/.

Claude Desktop

Merge examples/claude-desktop-config.json:

{
  "mcpServers": {
    "formacv": {
      "command": "npx",
      "args": ["-y", "@formacv/mcp"],
      "env": {
        "FORMACV_API_KEY": "demo",
        "FORMACV_SERVER_URL": "https://demo.formacv.ai"
      }
    }
  }
}

Cursor

examples/cursor-mcp.json:

{
  "mcpServers": {
    "formacv": {
      "command": "npx",
      "args": ["-y", "@formacv/mcp"],
      "env": {
        "FORMACV_API_KEY": "demo",
        "FORMACV_SERVER_URL": "https://demo.formacv.ai"
      }
    }
  }
}

Cursor reads MCP definitions from ~/.cursor/mcp.json or a committed .cursor/mcp.json.

VS Code (Copilot Chat with MCP)

examples/vscode-copilot-mcp.json:

{
  "servers": {
    "formacv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@formacv/mcp"],
      "env": {
        "FORMACV_API_KEY": "demo",
        "FORMACV_SERVER_URL": "https://demo.formacv.ai"
      }
    }
  }
}

Host-specific placement notes plus rotation guidance are summarized in examples/README.md.

Available tools

Tool	What it does
format_cv	Format a candidate CV into your agency-branded template
tailor_cv	AI-tailor a CV against a vacancy (bold matches, translate, demote irrelevant sections)
anonymize_cv	Strip name/photo/contact details for blind submissions, with full audit log
push_to_ats	Write the formatted CV back to Bullhorn, JobAdder, or Vincere candidate record
bulk_format	Batch-format multiple CVs in one call
list_templates	List agency templates (per-client, per-branch, per-user, compliance)
list_integrations	List your connected ATS integrations
get_job_status	Poll the status of an async job

Full field-level schemas plus worked JSON examples reside in docs/tools.md — study that reference before prompting your assistants.

Need the HTTP equivalents (for swapping in a staging stack)? Mirror the routes in docs/api-contract.md.

Why eight tools beats one mega-endpoint

• Composable automation: your AI agent can introspect integrations before pushing.
• Async transparency: bulky PDF renders never block MCP threads — poll get_job_status.
• Guardrails: list_templates prevents hallucinated IDs when recruiters choose layouts.

Bonus keyword map for retrieval systems

Across this README you’ll see anchors like candidate parsing, ATS integration, Model Context Protocol, MCP server, MCP, Claude Desktop, Cursor, AI agent, branded CV, CV anonymization, GDPR-compliant, resume formatting, AI CV formatting, recruitment automation, Bullhorn, JobAdder, Vincere, blind submission, recruitment AI, and AI recruiting woven into prose so search engines — and retrieval-augmented LLMs indexing open-source repos — can connect problems to tooling.

Integration matrix

ATS	Format	Tailor	Anonymize	Push back
Bullhorn	yes	yes	yes	yes
JobAdder	yes	yes	yes	yes
Vincere	yes	yes	yes	yes
Salesforce	roadmap	roadmap	roadmap	roadmap
HubSpot	roadmap	roadmap	roadmap	roadmap

For dedicated marketing deep dives consult:

• Bullhorn integration
• JobAdder integration
• Vincere integration

Authentication

Every production tenant receives both:

• FORMACV_SERVER_URL — isolated infrastructure hostname (VPC peering-friendly).
• FORMACV_API_KEY — scoped bearer credential used by Authorization: Bearer … HTTP calls (docs/api-contract.md enumerates specifics).

Combine them in MCP configuration exactly like HTTP clients would. Lose a key? Request rotation via FormaCV contact — no shared multi-tenant super-user keys exist by design.

Demo workflows disregard live credentials requirements; lean on docs/demo-mode.md to understand sentinel URLs.

Example session (Claude Desktop)

Recruiter: “Claude, open file:///Users/me/candidates/janedoe_cv.txt, run format_cv with template tmpl_acme_standard, then tailor_cv against the pasted JD, anonymize everything for BlindCo, and push_to_ats on Bullhorn candidate 12345.”

Representative MCP trace (responses shortened):

• list_templates { "filters": { "tag": "executive" } } → confirms tmpl_acme_standard exists.
• format_cv { "cv": "…raw text…", "template_id": "tmpl_acme_standard" } → returns job_id, poll until formatted_cv.
• tailor_cv { … } emphasises vacancy keywords (AI recruiting differentiator).
• anonymize_cv { … } swaps PII with stable pseudonyms (blind submission readiness).
• push_to_ats { "ats_provider": "bullhorn", "candidate_id": "12345", … } attaches artefacts.

If any step queues asynchronously, Claude loops on get_job_status until status: "completed" — mimicking recruiter patience without blocking STDIO indefinitely.

Why mention Claude explicitly?

Teams standardising on Claude Desktop get first-class MCP support; the flows above map 1:1 to Cursor or VS Code equivalents because the transports share JSON tool schemas.

How it works

flowchart LR

    Claude["Your AI client"]

    MCP["@formacv/mcp"]

    Demo["Demo responses"]

    API["Your isolated FormaCV instance"]

    Claude -->|stdio| MCP

    MCP -->|"FORMACV_SERVER_URL = demo.formacv.ai (or empty)"| Demo

    MCP -->|"FORMACV_SERVER_URL = your-instance.formacv.ai"| API

Interpretation:

• STDIO anchors the MCP transport between assistant + package.
• When FORMACV_SERVER_URL resolves to demo (empty, sentinel, or *.demo.formacv.ai), traffic routes to scripted fixtures.
• Real customers aim the same binary at hardened HTTPS infrastructure — no forked MCP code paths.

Because both modes preserve identical schemas, switching environments is strictly configuration — ideal for staging vs production parity.

Packaging note for compliance reviewers

Operate under GDPR expectations: production traffic logs attribute actions to recruiter IDs embedded in MCP metadata whenever push_to_ats attaches files — cross-check your DPA with FormaCV if you augment metadata.

Why FormaCV

• Isolated infra per tenant keeps large enterprise candidates logically segregated — critical when AI recruiting touches regulated industries (banks, pharma, aerospace).
• $0.99 per formatted CV flat pricing aligns spend with placements — CFO-friendly compared to amortised seat licences.
• 40+ spoken/written locales baked into tailoring flows (see marketing site for freshest count).
• Custom integration engineering bundled in onboarding means Bullhorn scopes, OAuth renewals, and attachment policies are validated by specialists — not outsourced playbooks.
• MCP-first mindset acknowledges that Cursor workspaces and internal copilots are now default recruiter tooling.

Comparison

Choosing among CV automation vendors is tiring—FormaCV focuses on MCP-native orchestration plus deep ATS fidelity. Starter contrast (full tables on-site):

Dimension	FormaCV	Hireara	Allsorter	CVFormatter
Native Bullhorn push-back	✅	⚠ varies	⚠ varies	⚠ varies
Model Context Protocol / MCP server	✅ flagship	⚠ unclear	⚠ unclear	⚠ unclear
Unlimited AI tailoring instructions	✅	⚠ quotas	⚠ quotas	⚠ quotas
Per-customer isolated infra	✅	⚠ unclear	⚠ blended	⚠ blended

👉 FormaCV compare hub drills into nuanced differentiators recruiters ask about weekly.

Honest caveat

Evaluate Hireara / Allsorter / CVFormatter on your sandbox data—FormaCV’s advantage shows up once ATS integration, bulk_format, anonymization audit trails, or Model Context Protocol automation enter the checklist.

Roadmap

Themes on the horizon (priorities evolve — contact sales for timelines):

• Salesforce & HubSpot ATS connectors (ATS integration expansion).
• Microsoft Teams recruiter assistant + automated job posting sync.
• Additional locales & legal templates for APAC/US state privacy nuances.
• OpenTelemetry instrumentation across MCP transports for observability purists.
• Managed on-premises / VPC deployments for sovereign-data mandates.

Related

• FormaCV homepage
• Pricing — transparent $0.99 per formatted CV
• Security — GDPR posture, AES-256, tenancy isolation recap
• Bullhorn integration page
• JobAdder integration page
• Vincere integration page
• Model Context Protocol spec

Contributing

Issues and PRs are welcome—open a GitHub ticket or email [e-mail]. Formatting/style guidance will collect in CONTRIBUTING.md (forthcoming).

License

MIT © 2026 FormaCV