The Virtual CV MCP server
Updated
Virtual CV’s MCP server lets a job seeker’s own AI assistant (ChatGPT, Claude, Claude Code) work with their Virtual CV: read and edit their CVs, read the jobs Virtual CV matched to them, keep their application tracker up to date, read their application kit to fill in a form and coach them from their Interview Practice reports. It speaks the Model Context Protocol at one address, connects when the job seeker signs in to Virtual CV from the assistant, and never spends credits, calls Wipperoz’s AI, applies for anyone or reaches another person’s data.
Connect
The server is https://api.wipperoz.com/v1/cv/mcp. It uses Streamable HTTP and keeps no session: every request is a POST answered on its own with JSON, and any other method is answered 405 with Allow: POST.
ChatGPT
ChatGPT connects by signing in. Add a custom app (connector), which needs Developer mode on a paid plan, with the server address https://api.wipperoz.com/v1/cv/mcp and OAuth as its authentication, then connect it: ChatGPT opens Virtual CV, where the job seeker signs in and allows it. What they choose there is under Signing in from an assistant below.
Claude (claude.ai, Claude Desktop and the mobile apps)
Add a custom connector with the server address https://api.wipperoz.com/v1/cv/mcp and connect it: Claude opens Virtual CV, where the job seeker signs in and allows it. There is no key to set: Virtual CV connects by signing in only.
Claude Code and other clients
Any client that signs in to remote MCP servers with OAuth connects the same way. In Claude Code, add the server, then authenticate it from /mcp:
claude mcp add --transport http virtual-cv https://api.wipperoz.com/v1/cv/mcp
A client that signs in through a loopback address (http://127.0.0.1) gets a warning on the consent page that any program on that computer can use its name.
Gemini isn’t supported yet.
Signing in from an assistant
Job seekers connect with OAuth 2.1 only; there are no API keys for Virtual CV. The assistant finds where to sign in from the server address alone: a request without a sign-in is answered 401 with WWW-Authenticate: Bearer realm="virtual-cv", resource_metadata="https://api.wipperoz.com/.well-known/oauth-protected-resource/v1/cv/mcp", scope="cv:read cv:write jobs:read applications:write kit:read practice:read". That document names the authorization server, https://api.wipperoz.com, and lists the same six scopes in scopes_supported. Sign-in is the authorization code flow with PKCE (S256), for the resource https://api.wipperoz.com/v1/cv/mcp; a client identifies itself with a client ID metadata document or registers dynamically. A request that names no scope asks for all six, and the job seeker narrows them; scope names the server doesn’t grant are dropped.
If the job seeker isn’t signed in to Virtual CV, they sign in first, with a password or with Google, and come back to the same page. Virtual CV shows them the assistant’s name, the account it will work for (theirs, by email) and the address it sends them back to, and they tick what it may do, at least one:
| Permission | Scope | Tools |
|---|---|---|
| See your CVs | cv:read |
list_cvs, get_cv |
| Create and edit your CVs | cv:write |
create_cv, update_cv_section, duplicate_cv |
| See the jobs Virtual CV matched to you | jobs:read |
list_job_matches, get_job |
| Log and update your job applications | applications:write |
save_job, log_application, update_application, list_applications |
| Read your application kit | kit:read |
get_application_kit |
| See your Interview Practice reports | practice:read |
list_practice_sessions, get_practice_report, start_practice |
The scopes are flat: none includes another, so an assistant with cv:write alone can’t read a CV. A consent request lasts 10 minutes.
Only a Virtual CV (job seeker) account can allow a connection here; an Orbit account is refused. The connection belongs to the job seeker who allowed it and reaches only their own data. It is listed in Virtual CV → Settings → Security → Connected assistants, with what it may do, when it was connected and when it was last used, and Disconnect there refuses its next request. Closing the Virtual CV account deletes every connection with its codes and tokens, and the job seeker’s data export lists their connections (account/assistant-connections.json). A client can end its own connection with the revocation endpoint in the authorization server’s metadata (RFC 7009): either of its tokens ends the whole connection. Access tokens last an hour and refresh tokens rotate, each lasting 30 days, so an assistant that goes 30 days without using Virtual CV has to sign in again.
A connection is for this server only. An Orbit API key or an Orbit connection is refused here, and a Virtual CV connection is refused by Orbit. jobs:read and applications:write are also Orbit scope names, but a Virtual CV token’s jobs:read reads the job seeker’s own matches and nothing of Orbit’s.
The tools
| Tool | What it does | Scope |
|---|---|---|
list_cvs |
List CVs. The job seeker’s CVs, last edited first: cv_id, name, headline, status (draft, live or offline), completeness, created_at, updated_at and url, with total and max_cvs. |
cv:read |
get_cv |
Read a CV. One CV (cv_id), section by section, with what is verified. |
cv:read |
create_cv |
Create a CV. A new private CV from name and at least one section. Answers cv_id, name, created_at and url. |
cv:write |
update_cv_section |
Update a CV section. Replaces one section of a CV (cv_id) with content. Answers cv_id, section, changed, updated_at and url. |
cv:write |
duplicate_cv |
Duplicate a CV. A private copy of a CV (cv_id) under a new name, as the app’s own duplicate makes it. Answers the new cv_id, source_cv_id, name, created_at and url. |
cv:write |
list_job_matches |
List job matches. The jobs Virtual CV already matched to the job seeker, as their Jobs page shows them: employers’ invitations first, then best fit. Each has job_id, cv_id, title, company, location, fit (0 to 100), posted_at, source, invited, link and why it matched. cv_id narrows to one CV; limit is 20 by default, 50 at most. |
jobs:read |
get_job |
Read a job match. One match (job_id, and cv_id or the best fit among the job seeker’s CVs) in full: the description, the role’s skills, matched and missing skills, strengths, gaps, the AI insight when there is one, and an employer’s invitation. |
jobs:read |
save_job |
Save a job. Adds a job to the tracker as saved: title, company, and optionally url, site and location. Answers application_id. |
applications:write |
log_application |
Log an application. Records that the job seeker applied to a saved job (application_id) with one of their CVs (cv_id), on applied_on (today when left out). Answers status, applied_on, tracked_link and tracked_link_live. |
applications:write |
update_application |
Update an application. Sets status (applied, interviewing, offer, rejected or withdrawn) and, optionally, note, up to 500 characters ("" clears it). |
applications:write |
list_applications |
List applications. The tracker, newest first, up to 100 (total says how many): each entry’s status, cv_id, applied_on, note, tracked_link and link_activity (opens, first_opened_at, last_opened_at), and the applications made on Wipperoz. |
applications:write |
get_application_kit |
Get the application kit. What application forms ask, from the job seeker’s Virtual CV: name, contact details, links, work history, education, skills, certifications and languages, each marked verified or not, their saved answers, 10-minute links to their CV’s PDF and a cover letter for company, and an application’s tracked link. |
kit:read |
list_practice_sessions |
List practice sessions. The job seeker’s Interview Practice sessions, newest first (up to 50; has_more says there are older ones): session_id, dates, status, the role practised, interview type and length, style, language, the CV used, and the report’s status with its overall result. |
practice:read |
get_practice_report |
Read a practice report. One report (session_id), text only, as the report page shows it: strengths, priorities, each question as asked with the job seeker’s answers and their feedback, retries, and delivery (pace, pauses, filler phrases). report_not_ready while it is being made. |
practice:read |
start_practice |
Open Interview Practice. A link that opens Interview Practice in Virtual CV with a role filled in: one of the job seeker’s matches (job_id, which also needs jobs:read) or a title, with company and job_link if known. It starts nothing: the job seeker chooses the interview and starts it in Virtual CV. |
practice:read |
Every tool has a title and MCP annotations, and tools/list names all fifteen (the three Interview Practice tools only while they are offered); a tool the connection doesn’t carry the scope for answers forbidden_scope. The nine that only read (list_cvs, get_cv, list_job_matches, get_job, list_applications, get_application_kit, list_practice_sessions, get_practice_report and start_practice) are marked readOnlyHint: true. create_cv, duplicate_cv and save_job write without overwriting anything (destructiveHint: false). update_cv_section, update_application and log_application can replace what was there (logging an application again replaces its CV and date), so they are marked destructiveHint: true and idempotentHint: true. Inputs are strict: an unknown argument is refused before the tool runs. url opens the CV in the Virtual CV builder.
A Virtual CV is live: when the CV is published, update_cv_section changes its public page at once. The tool’s description tells the assistant to confirm with the job seeker before it overwrites a section.
Sections
A CV’s sections are fixed. content in update_cv_section is the whole section: an object for personal and summary, a list for the rest. What it leaves out is cleared, except what is read-only, which is kept.
| Section | Holds |
|---|---|
personal |
headline, first_name, last_name, email, phone, location, right_to_work; identity_verified is read-only |
summary |
summary, short_summary, highlights |
experience |
roles: title, company, location, start_date, end_date, current, description, up to three metrics (value, label); skills_used, verified and verified_by are read-only |
education |
institution, degree, field, location, start_date, end_date, current, description |
skills |
name, category, group; level is worked out by Virtual CV and read-only |
languages |
name, proficiency |
awards |
awards and certifications: name, category, date, issuer, description, credential_id, credential_url, expiry_date; verified is read-only |
projects |
name, category, contribution, blurb, description, location, start_date, end_date, current, metric |
interests |
a list of words |
social_links |
platform, url, username, visible |
references |
name only, read-only: references’ contact details are never returned and can’t be written |
create_cv takes the same sections except references. It takes structured data only: there is no file, document or file-URL argument, and it never imports, translates or tailors.
Verified content is read-only
Some of a CV is verified: a role at an employer the job seeker verified with their work email, a role someone endorsed, an award matching a credential verified with Credly or Microsoft Learn, and, once their identity is verified, their first and last name. get_cv marks each one (verified, verified_by, identity_verified).
- A verified entry must come back unchanged in
content, in any position. Changed or missing, the update is refused withverified_read_only. - With a verified identity,
first_nameandlast_nameare kept when left out, and refused when different. - Nothing written over MCP gets a verified badge. A write whose result would show one (a new role at the verified employer, an award matching a verified credential, a name on a new CV once the identity is verified) is refused with
verification_not_allowed.duplicate_cvcopies verified entries as the app does, and they stay read-only on the copy.
Job matches
list_job_matches and get_job read the matches Virtual CV has already made for the job seeker, as their Jobs page shows them, and only their current ones: another job is not_found. Neither runs a match, searches other jobs, reads a balance or calls a model. link is where the job seeker applies: an Orbit role’s apply page on www.wipperoz.com, or the original ad. No tool applies. To tailor a CV to a job, an assistant duplicates the CV the job matched (duplicate_cv) and changes the copy with the job seeker’s own facts (update_cv_section).
The application tracker
save_job, log_application, update_application and list_applications write and read the entries the job seeker’s Applications page shows, at once, through the same checks as the page.
- A job is a
titleandcompany(up to 200 characters each), and optionally aurl(https, up to 2,048; a parameter that looks like a sign-in, such as a token, a code, a key or a session, or that holds an email address, is dropped before it is stored), thesite(up to 100; taken from the link when left out) and alocation(up to 200). Never the ad’s text or the conversation. log_applicationmakes a saved job an application (applied; one already further along keeps its status), datedapplied_onor today, and gives it atracked_linkthe first time it has a CV:https://wprz.me/and a code unique to that application. The link opens the CV’s public page, and only while that CV is published (tracked_link_live); when it isn’t,tracked_link_notesays so.- An open is counted once per visitor per UTC day, in the tracker only: it is never recorded as a view of the CV. A
HEADrequest, a browser prefetch or prerender, and a fetch with no user agent or with a link-preview or mail-scanner one are never counted. An open means someone opened the link, not that the employer read the CV. The job seeker gets a notification and an email on the first open, then at most one a day per link, unless they turn them off. - Statuses are
saved,applied,interviewing,offer,rejectedandwithdrawn. - Applications made on Wipperoz, to an Orbit role, are listed with
source: "orbit",read_only: trueandstatus: "applied". The employer moves them along, solog_applicationandupdate_applicationanswerread_onlyfor one. - No tool deletes an entry. A job seeker can hold up to 2,000 entries; past that
save_jobanswersapplication_limit.
The application kit
get_application_kit returns the job seeker’s contact details, their email address and phone number, as application forms ask for them, and only to their own assistant. get_cv shows them too, in the personal section.
- Which CV:
cv_idwhen given; else the CV on the application (application_id); else the newest published CV, else the newest.cv.chosen_becausesays which (requested,applicationordefault). - Which cover letter: one of that CV’s letters written for
company, when there is one. - Files: the CV’s PDF and the cover letter, each with a
status:ready,out_of_date(the CV or letter changed after the PDF was made; still linked) ornot_generated(no link: the job seeker downloads it once in the app). Links last 10 minutes (expires_at). - The application: with
application_id, its title, company, status and tracked link, so the assistant can give the employer the tracked link rather than the usual one.
It reads and never writes: no tool saves an answer. Its description tells the assistant to fill a form from the kit only, never invent, leave every demographic or legal question (ethnicity, gender, disability, age, religion, health, criminal record) to the job seeker, and never submit or move to the next step unless they say so.
Interview Practice reports
list_practice_sessions and get_practice_report read the job seeker’s own Interview Practice sessions and reports as text. They never return a recording, audio or video, or anyone else’s practice. start_practice only builds a link: it creates no session and charges nothing. The job seeker reviews the role, chooses the interview and starts it in Virtual CV, where it is recorded and its report written. The three tools are listed only while Interview Practice is offered to assistants. Privacy and recordings in practice interviews says who sees what.
Errors
A tool that won’t do what was asked answers with a tool error, isError: true, and error.code with one sentence the assistant can relay:
forbidden_scope: the connection doesn’t carry the scope the tool needs;error.scopenames it.not_found: no such CV, job match, application or practice session for this job seeker. Another person’s isnot_foundtoo.invalid_input: an argument doesn’t fit;error.fieldnames it.verified_read_only: the update changed or left out something verified;error.sectionanderror.itemssay what.verification_not_allowed: the write would have shown a verified badge on something the assistant wrote;error.itemssays which.cv_limit: the job seeker already haserror.max_cvsCVs.read_only: the application was made on Wipperoz, and only the employer moves it along.application_limit: the job seeker already trackserror.maxapplications.report_not_ready: the practice report is still being made; try again in a few minutes.internal_error: nothing was changed; try again.
The HTTP layer answers a JSON-RPC error:
| Status | error.code |
When |
|---|---|---|
401 |
-32001 |
No Virtual CV sign-in, or one that was disconnected or has expired, or an Orbit key. WWW-Authenticate says where to sign in. |
405 |
-32000 |
A method other than POST. |
429 |
-32029 |
Over a limit (below). error.data has window, limit, resets_at and retry_after_seconds. |
400 |
-32700 |
The body isn’t JSON. |
500 |
-32603 |
The server couldn’t answer. |
Limits
Each job seeker has, by default:
- 60 requests a minute. Every request counts one, except a tool call, which counts as below.
- 500 units a day, counted in tool calls only: a read counts one and a write two. The writes are
create_cv,update_cv_section,duplicate_cv,save_job,log_applicationandupdate_application. The day resets at 00:00 UTC. - 10 CVs:
create_cvandduplicate_cvare refused withcv_limitonce the job seeker has that many.
Past a limit the server answers 429 with X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After, and the message says when it resets. A call refused for the daily limit costs nothing.
What it never does
- Spend credits. Every tool is free: none reads a balance, charges or calls a model.
- Apply for anyone. No tool submits an application or contacts an employer: links are the job seeker’s to open.
- Delete or publish. No tool deletes a CV or an application, or publishes a CV or takes it offline.
- Import a file. A PDF is imported in the Virtual CV app, where Wipperoz’s AI reads it.
- Share another person’s data. No tool returns references’ contact details, endorsers, anyone else’s CV or applications, or internal ids other than
cv_id,job_idandapplication_id. - Reach another job seeker. Every tool works on the data of the person who signed in.