@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)

1. Ensure Node.js 18+ is available (the MCP transport launches via npx).
2. 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

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

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

For dedicated marketing deep dives consult:

• Bullhorn integration
• JobAdder integration
• Vincere integration

Authentication

Every production tenant receives both:

1. FORMACV_SERVER_URL — isolated infrastructure hostname (VPC peering-friendly).
2. 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):

1. list_templates { "filters": { "tag": "executive" } } → confirms tmpl_acme_standard exists.
2. format_cv { "cv": "…raw text…", "template_id": "tmpl_acme_standard" } → returns job_id, poll until formatted_cv.
3. tailor_cv { … } emphasises vacancy keywords (AI recruiting differentiator).
4. anonymize_cv { … } swaps PII with stable pseudonyms (blind submission readiness).
5. 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.