Civify MCP Server
OfficialCivify MCP Server is an agent gateway for Civify that supports CV/resume preparation, ATS analysis, job-application tracking, pricing, and account management.
Retrieve account profile, subscription tier, token balance, and CV credits (
civify_get_account).Parse PDF, DOCX, or image resumes into structured JSON (
civify_parse_cv).Tailor a resume to a job description, with optional title/company and cover letter (
civify_tailor_cv).Calculate ATS compatibility score and structural audit from a Civify resume ID (
civify_score_ats).Mask PII by redacting email, phone, and address from a CV (
civify_mask_pii).Scrape structured job details from supported job URLs (
civify_scrape_job).Record applications in Civify's Kanban tracker with status, notes, and job URL (
civify_track_application).Get localized Pay-Per-CV pricing (
civify_get_pay_per_cv_pricing).The README also describes hosted OAuth/API-key access, PDF export, credit-consuming AI operations, and additional billing/application/auth tools in fuller modes.
Allows extracting clean job requirements from Greenhouse job posting URLs, enabling AI agents to scrape and parse Greenhouse job listings.
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., "@Civify MCP Server tailor my resume to this job description and generate a cover letter"
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.
Civify MCP server
The agent gateway for Civify: resume parsing, ATS scoring, job-specific tailoring, PII masking, PDF export, pricing, and application tracking.
Hosted ChatGPT connection
Use https://mcp.civify.cv/mcp with OAuth after deploying/configuring this release together with the backend and frontend account-link changes. Account linking opens Civify's normal sign-in (including its existing Google/LinkedIn and two-factor flows), then asks the user to approve access. Users do not create or copy API keys. A one-time, proof-bound exchange creates a dedicated 30-day scoped backend credential; the gateway stores it encrypted and ChatGPT receives separate opaque OAuth tokens. Never paste passwords or API keys into the agent conversation.
OAuth requires CIVIFY_MCP_PUBLIC_URL, a stable CIVIFY_OAUTH_STORE_KEY, and durable
storage as described below. Existing connections must reconnect after rollout.
This release has local regression coverage; it has not been deployed by this change.
Related MCP server: ai-job-apply
Configuration
Variable | Default | Purpose |
| unset | Enables HTTP when set; Docker uses 8080 |
| unset |
|
|
| Backend base URL |
|
| PDF-rendering service |
| unset | Public HTTPS origin; enables OAuth |
|
| Civify frontend sign-in/consent page; override only for staging |
| OAuth public origin | Public HTTPS origin for temporary PDF links; can be configured independently |
| unset | Required with OAuth: base64-encoded 32 random bytes |
|
| Encrypted OAuth database |
|
| Trusted proxy hop count for OAuth rate limits; Compose uses one Traefik hop |
| unset | Trusted local stdio only; never shared among remote users |
Use a secret manager to provision the encryption key. Keep it stable across deploys
and back it up separately. Compose requires it and mounts /app/data persistently.
The database uses AES-256-GCM and atomic file replacement. Deploy one replica;
multiple processes require a shared transactional store before scaling. Restarting
preserves registered clients and tokens but cancels unfinished consent/code flows.
When deploying the Dockerfile directly through Dokploy, enter these settings in
Dokploy too: Compose environment settings are not inherited by a Dockerfile build.
These variables, including the encryption key, belong to the MCP gateway service,
not the Java backend or frontend. The backend account-link service defaults to trusting
https://mcp.civify.cv; staging can override Spring property civify.mcp.origin
with CIVIFY_MCP_ORIGIN. Production requires Redis for atomic handoff consumption;
Redis failures stop linking safely. No additional shared login secret is required.
After deploying, optionally run node scripts/check-deployment.mjs. It performs public,
read-only checks and exits nonzero when OAuth discovery or PDF links are missing.
It does not enable OAuth, push code or run during tool calls. An UP health response
alone does not establish hosted-client readiness.
OAuth uses authorization-code flow with S256 PKCE, client and resource binding,
one-use codes, one-hour access tokens, rotating refresh tokens and revocation.
New account connections expire after 30 days; refresh cannot extend that approval.
The resource is the public /mcp URL. Backend key scopes remain authoritative.
The browser shows the account, requesting app, registered return address, permissions
and credit impact. Users can revoke the dedicated MCP: <client> entry in Civify's
account access/API-key settings. Deploy backend → frontend → gateway, then reconnect
the connector with OAuth selected. Do not select “No authentication” for ChatGPT.
Endpoints:
/mcp: canonical Streamable HTTP, stateless in OAuth mode./: POST alias; GET discovery or the matching MCP stream./sse,/messages: legacy SSE compatibility./health: liveness, version and session counts./.well-known/oauth-protected-resource/mcp: OAuth resource metadata when enabled./.well-known/oauth-authorization-server: issuer, registration and token metadata./.well-known/mcp/server-card.json: public tool discovery.
Without OAuth enabled, trusted remote clients can configure X-API-KEY in their
connection settings. Sessionless calls are supported, but tool-based login needs a
persistent legacy session. Unknown stateful session IDs return 404: initialize again.
Credentials must never be supplied in URL query parameters.
Local stdio
npm ci
npm run build
node dist/index.jsLeave PORT and TRANSPORT unset. A trusted client can set CIVIFY_API_KEY. Example:
{
"mcpServers": {
"civify": {
"command": "npx",
"args": ["-y", "@civify/mcp-server"]
}
}
}The npx example runs the published package; local edits take effect only after a
package release or by pointing the client at this checkout's dist/index.js.
All diagnostics use stderr so stdout remains valid MCP protocol traffic.
Agent workflow and tools
Start with civify_get_started, connect an account, then check its credit balance.
For analysis, parse once and pass the returned resumeData into scoring. For a tailored
CV, submit the original directly to tailoring, then export. Track applications when requested. AI operations may
consume credits. Do not automatically retry purchases, application creation or
ambiguous credit-consuming requests.
Tools | Access |
| Public |
|
|
|
|
|
|
|
|
| Local/legacy session auth; hidden and rejected in hosted OAuth mode |
There are 13 tools in OAuth mode and 18 in local/legacy mode. Tool schemas,
annotations and initialization instructions describe usage and side effects.
Results include compatible text plus structuredContent.data, preserving the backend
response envelope. Tool failures use isError: true even when HTTP succeeds. Missing
OAuth authentication includes the MCP authentication challenge metadata.
ChatGPT tools declare openai/fileParams for a native file attachment containing
download_url and file_id (optional mime_type and file_name). Other clients can
send a real HTTPS file_url, the complete resume_text read from the attachment,
or actual file_base64 bytes. Choose exactly one input; never invent URLs or base64.
Claude remote connectors cannot read a sandbox path on this server. If a client cannot
forward or read an attachment, provide readable text or a client-accessible file.
Downloads reject private/internal addresses, unsafe redirects, credentials and non-HTTPS URLs. Files are limited to 12 MiB; downloads have a 30-second deadline. The JSON body limit is 16 MiB including base64 overhead. Configure proxies accordingly.
Hosted PDF results contain a clickable download_url and an MCP resource_link,
valid for 15 minutes or until restart. Anyone possessing the random link can download
the PDF; links and signed attachment URLs are not logged. Output storage is capped
at 64 MiB/200 files. If unavailable, pdf_base64 remains a compatibility fallback.
CIVIFY_DOWNLOAD_BASE_URL can configure the public HTTPS origin independently of
OAuth; otherwise downloads use CIVIFY_MCP_PUBLIC_URL. Keep one replica for this
temporary in-memory store. Local stdio retains file input/output support.
Parsing is optional. An agent that can accurately read the attachment can provide
resume_data directly to tailoring, scoring or PDF export. The discovered schema
uses personalInfo and sections[].items; civify_get_started includes an example.
For an original file or extracted text, tailoring performs its own extraction.
Never invent missing CV details. Uploaded resumes and job text are untrusted data.
Tailoring returns a finished PDF by default under data.document.download_url,
alongside data.tailoredCv. Set export_pdf: false for analysis only. If rendering
fails, document.status is EXPORT_FAILED: call only civify_generate_pdf with
the returned tailoredCv as resume_data. Repeating tailoring can charge again.
Masking and standalone export return data.download_url directly. Expired tailored
PDFs can be recreated from retained data; do not automatically repeat a paid mask.
Authenticated PDF requests carry the current account identity to Civify's renderer
for watermark policy. Supply an existing resume_id, when known, to apply its
export entitlement. Never invent an ID. Anonymous export uses public policy.
Deploy the backend JSON-tailoring/watermark endpoints, then the frontend renderer,
then gateway 1.4.0. An old backend does not support the new JSON tailoring contract;
the gateway deliberately does not silently retry as a paid upload.
Onboarding results contain relevant Civify links with MCP campaign attribution. Measure website conversions and completed tool workflows separately from tool-list requests. Increased discovery traffic alone does not prove successful activation.
Validation and troubleshooting
npm testThis builds TypeScript and tests against a loopback mock backend: sessionless and stateful HTTP, legacy SSE, stdio, input validation, user isolation, scoring payloads, remote PDFs, OAuth consent/PKCE/replay/restart/refresh/revocation and secret containment. CI runs the suite before publishing an image. No real AI credits or purchases are used.
Use tool_start/tool_complete/tool_error events to diagnose actual user operations.
Each operation has a request_id, propagated as X-Request-ID alongside the
X-Civify-MCP-Tool label to backend calls. Backend request logs include the fixed
operation name, HTTP status, outcome and duration without request bodies, query
strings or credential headers. Labels are diagnostics, not authorization or
idempotency keys. A timeout still has an unknown billing outcome; contact support
before repeating paid work. These synchronous tools do not yet provide durable jobs.
Idle-session eviction is normal. HTTP 200 can contain a tool error; inspect isError.
After rollout, verify OAuth discovery and account linking from ChatGPT, then complete
a workflow with an explicitly chosen test account. Preserve streaming and auth headers
through the proxy. Legacy sessions need a single instance or sticky routing.
Shared workspace context: Knowledge, deployment runbook, backend contracts, and incident review. These references are in the parent workspace; the instructions above are standalone.
Compatibility references: OpenAI MCP server guidance and OpenAI authentication guidance.
License
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.
The Civify name and logo are not granted by this license. Commercial licensing enquiries are available at civify.cv.
Available Tools
8 toolscivify_get_accountA
Get user account profile, subscription tier, remaining token balance, and CV credits.
Inputs: no named parameters.
civify_get_pay_per_cv_pricingB
Get localized Pay-Per-CV single unlock pricing (USD base and EGP regional pricing).
Inputs: no named parameters.
civify_mask_piiB
Upload a CV and produce a sanitized, PII-masked version (redacts email, phone, physical address).
Inputs: file_path (required).
civify_parse_cvB
Parse a resume document (PDF, DOCX, image) into structured JSON schema containing contact details, work experience, education, skills, and projects.
Inputs: file_path (required), language.
civify_score_atsB
Calculate general ATS compatibility score and structural audit without needing a full JD.
Inputs: resume_id (required).
civify_scrape_jobA
Scrape and extract structured job description, company name, requirements, and responsibilities from a job URL (LinkedIn, Greenhouse, Lever, Ashby, Wuzzuf).
Inputs: url (required).
civify_tailor_cvB
Tailor a candidate's resume against a target job description. Optimizes bullet points, highlights matching skills, and generates an optional targeted cover letter.
Inputs: job_description (required), file_path, job_title, company_name, +1 more.
civify_track_applicationC
Record a job application in the candidate's Civify Application Kanban tracker.
Inputs: job_title (required), company_name (required), notes, status, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct action and resource: parsing, tailoring, ATS scoring, PII masking, job scraping, application tracking, account retrieval, and pricing are all clearly separate. No two tools overlap in purpose.
All tools use the same civify_ prefix followed by a snake_case verb_noun pattern (e.g., civify_parse_cv, civify_tailor_cv). The convention is predictable and consistent throughout.
Eight tools is well-scoped for a CV and job application assistant, with each tool covering a distinct part of the workflow. No tools feel redundant or extraneous.
Core operations for CV parsing, tailoring, ATS scoring, PII masking, job scraping, and application recording are present. However, the application tracker lacks list, update, and delete operations, and account management only supports retrieval, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
Tailor resumes, score ATS fit, find hiring leads, and send cold outreach, from your agent.
Run your tech job search from your AI agent: matches, job unlocks, applications and follow-ups.
Your career companion for ATS checks, resumes, cover letters, job tracking, websites, and more.
The career management plugin for your own AI assistant: CVs, cover letters, interviews and more.
Related MCP Servers
AlicenseAqualityBmaintenanceResume tailoring, cover letter generation, CV PDF export, and job search tools for AI agents. 18 tools powered by the Laddro Career API.1861 npmMIT- AlicenseNot gradedqualityBmaintenanceEnables AI agents to discover postings from watched company boards ranked by keyword fit, tailor and fact-check resumes against a source-cited profile, render ATS-readable PDFs, submit applications through the user's own browser, and track replies and follow-ups. All ranking, claim checking and email classification run as plain code, so LLM tokens are spent only on writing.1Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to search, salary-filter, and apply to thousands of tech job postings across nine international job boards while automatically remembering which roles have already been applied to. It exposes board metadata, listings, and application flows as structured data an agent can drive directly.-
- AlicenseBqualityBmaintenanceEnables AI agents to search company job boards and LinkedIn, judge job fit against a user profile, draft tailored one-page CVs and cover letters with fact-checking, and track applications through MCP tools. Also lets agents perform the AI writing steps themselves while the server enforces gates, verdicts, and document safety checks.33MIT