O servidor MCP do Virtual CV
Atualizado
O servidor MCP do Virtual CV permite que o assistente de IA de uma pessoa à procura de emprego (ChatGPT, Claude, Claude Code) trabalhe com o seu Virtual CV: ler e editar os seus CVs, ler as ofertas que o Virtual CV encontrou para ela, manter atualizado o acompanhamento das suas candidaturas, ler o seu kit de candidatura para preencher um formulário e ajudá-la a preparar-se com os relatórios das suas entrevistas de prática. Fala o Model Context Protocol num único endereço, liga-se quando a pessoa inicia sessão no Virtual CV a partir do assistente, e nunca gasta créditos, nunca usa a IA da Wipperoz, nunca se candidata por ninguém nem acede a dados de outras pessoas.
Ligar
O servidor é https://api.wipperoz.com/v1/cv/mcp. Usa Streamable HTTP e não guarda sessão: cada pedido é um POST com a sua própria resposta em JSON, e qualquer outro método recebe 405 com Allow: POST.
ChatGPT
O ChatGPT liga-se através de um início de sessão. Adicione uma aplicação personalizada (conector), que precisa do modo de programador num plano pago, com o endereço do servidor https://api.wipperoz.com/v1/cv/mcp e OAuth como autenticação, e ligue-a: o ChatGPT abre o Virtual CV, onde a pessoa inicia sessão e lhe dá permissão. O que escolhe aí está descrito mais abaixo, em Iniciar sessão a partir de um assistente.
Claude (claude.ai, Claude Desktop e as aplicações móveis)
Adicione um conector personalizado com o endereço do servidor https://api.wipperoz.com/v1/cv/mcp e ligue-o: o Claude abre o Virtual CV, onde a pessoa inicia sessão e lhe dá permissão. Não há nenhuma chave a definir: o Virtual CV só se liga com início de sessão.
Claude Code e outros clientes
Qualquer cliente que inicie sessão em servidores MCP remotos com OAuth liga-se da mesma forma. No Claude Code, adicione o servidor e depois autentique-o a partir de /mcp:
claude mcp add --transport http virtual-cv https://api.wipperoz.com/v1/cv/mcp
Um cliente que inicia sessão através de um endereço local (http://127.0.0.1) mostra, na página de consentimento, um aviso de que qualquer programa desse computador pode usar o seu nome.
O Gemini ainda não é suportado.
Iniciar sessão a partir de um assistente
As pessoas ligam-se apenas com OAuth 2.1; o Virtual CV não tem chaves de API. O assistente encontra onde iniciar sessão só a partir do endereço do servidor: um pedido sem início de sessão recebe 401 com 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". Esse documento indica o servidor de autorização, https://api.wipperoz.com, e lista os mesmos seis âmbitos em scopes_supported. O início de sessão é o fluxo de código de autorização com PKCE (S256), para o recurso https://api.wipperoz.com/v1/cv/mcp; um cliente identifica-se com um documento de metadados de cliente ou regista-se dinamicamente. Um pedido que não indica nenhum âmbito pede os seis, e a pessoa escolhe entre eles; os nomes que o servidor não concede são ignorados.
Se a pessoa não tiver sessão iniciada no Virtual CV, começa por iniciar sessão, com palavra-passe ou com a Google, e volta à mesma página. O Virtual CV mostra-lhe o nome do assistente, a conta para a qual vai trabalhar (a sua, pelo endereço de e-mail) e o endereço para onde o envia de volta, e marca o que ele pode fazer, pelo menos uma opção:
| Permissão | Âmbito | Ferramentas |
|---|---|---|
| Ver os seus CVs | cv:read |
list_cvs, get_cv |
| Criar e editar os seus CVs | cv:write |
create_cv, update_cv_section, duplicate_cv |
| Ver as ofertas de emprego que o Virtual CV encontrou para si | jobs:read |
list_job_matches, get_job |
| Registar e atualizar as suas candidaturas | applications:write |
save_job, log_application, update_application, list_applications |
| Ler o seu kit de candidatura | kit:read |
get_application_kit |
| Ver os seus relatórios de entrevistas de prática | practice:read |
list_practice_sessions, get_practice_report, start_practice |
Os âmbitos são independentes: nenhum inclui outro, por isso um assistente só com cv:write não consegue ler um CV. Um pedido de consentimento dura 10 minutos.
Aqui, só uma conta do Virtual CV (de uma pessoa à procura de emprego) pode autorizar uma ligação; uma conta do Orbit é recusada. A ligação pertence à pessoa que a autorizou e só chega aos seus próprios dados. Aparece em Virtual CV → Configurações → Segurança → Assistentes ligados, com o que pode fazer, quando foi ligada e quando foi usada pela última vez, e Desligar aí recusa o pedido seguinte. Encerrar a conta do Virtual CV elimina todas as ligações com os seus códigos e tokens, e a exportação de dados da pessoa lista as suas ligações (account/assistant-connections.json). Um cliente pode terminar a sua própria ligação com o endpoint de revogação dos metadados do servidor de autorização (RFC 7009): qualquer um dos seus tokens termina a ligação inteira. Os tokens de acesso duram uma hora e os de atualização são renovados a cada uso e duram 30 dias cada um, por isso um assistente que passe 30 dias sem usar o Virtual CV tem de voltar a iniciar sessão.
Uma ligação serve apenas para este servidor. Uma chave de API ou uma ligação do Orbit é recusada aqui, e uma ligação do Virtual CV é recusada pelo Orbit. jobs:read e applications:write também são nomes de âmbitos do Orbit, mas o jobs:read de um token do Virtual CV lê as ofertas compatíveis da própria pessoa e nada do Orbit.
As ferramentas
| Ferramenta | O que faz | Âmbito |
|---|---|---|
list_cvs |
List CVs. Os CVs da pessoa, do último editado para o primeiro: cv_id, name, headline, status (draft, live ou offline), completeness, created_at, updated_at e url, com total e max_cvs. |
cv:read |
get_cv |
Read a CV. Um CV (cv_id), secção a secção, com o que está verificado. |
cv:read |
create_cv |
Create a CV. Um CV privado novo a partir de name e de pelo menos uma secção. Responde cv_id, name, created_at e url. |
cv:write |
update_cv_section |
Update a CV section. Substitui uma secção (section) de um CV (cv_id) por content. Responde cv_id, section, changed, updated_at e url. |
cv:write |
duplicate_cv |
Duplicate a CV. Uma cópia privada de um CV (cv_id) com um nome novo (name), tal como a própria aplicação a faz. Responde o novo cv_id, source_cv_id, name, created_at e url. |
cv:write |
list_job_matches |
List job matches. As ofertas que o Virtual CV já encontrou para a pessoa, tal como a sua página Vagas as mostra: primeiro os convites de empregadores e depois a melhor compatibilidade. Cada uma tem job_id, cv_id, title, company, location, fit (de 0 a 100), posted_at, source, invited, link e porque é compatível. cv_id limita a um CV; limit é 20 por predefinição e 50 no máximo. |
jobs:read |
get_job |
Read a job match. Uma oferta (job_id, e cv_id ou o CV da pessoa mais compatível) por inteiro: a descrição, as competências da função, as competências que tem e as que faltam, os pontos fortes, as lacunas, a análise da IA quando existe e o convite de um empregador. |
jobs:read |
save_job |
Save a job. Adiciona uma oferta ao acompanhamento como saved: title, company e, se quiser, url, site e location. Responde application_id. |
applications:write |
log_application |
Log an application. Regista que a pessoa se candidatou a uma oferta guardada (application_id) com um dos seus CVs (cv_id), no dia applied_on (hoje, se for omitido). Responde status, applied_on, tracked_link e tracked_link_live. |
applications:write |
update_application |
Update an application. Define status (applied, interviewing, offer, rejected ou withdrawn) e, se quiser, note, até 500 caracteres ("" apaga-a). |
applications:write |
list_applications |
List applications. O acompanhamento, da mais recente para a mais antiga, até 100 (total diz quantas há): o status, cv_id, applied_on, note, tracked_link e link_activity (opens, first_opened_at, last_opened_at) de cada entrada, e as candidaturas feitas na Wipperoz. |
applications:write |
get_application_kit |
Get the application kit. O que os formulários de candidatura pedem, a partir do Virtual CV da pessoa: nome, contactos, links, percurso, formação, competências, certificações e línguas, cada um marcado como verificado ou não, as suas respostas guardadas, links de 10 minutos para o PDF do seu CV e para uma carta de apresentação para company, e o link de acompanhamento de uma candidatura. |
kit:read |
list_practice_sessions |
List practice sessions. As sessões de entrevistas de prática da pessoa, da mais recente para a mais antiga (até 50; has_more indica que há mais antigas): session_id, datas, estado, a função praticada, tipo e duração da entrevista, estilo, idioma, o CV usado e o estado do relatório com o seu resultado geral. |
practice:read |
get_practice_report |
Read a practice report. Um relatório (session_id), só texto, tal como a página do relatório o mostra: pontos fortes, prioridades, cada pergunta tal como foi feita com as respostas da pessoa e a respetiva avaliação, as novas tentativas e a forma de falar (ritmo, pausas, palavras de enchimento). report_not_ready enquanto está a ser preparado. |
practice:read |
start_practice |
Open Interview Practice. Um link que abre a prática no Virtual CV com uma função já indicada: uma das suas ofertas (job_id, que também precisa de jobs:read) ou um title, com company e job_link se os tiver. Não inicia nada: a pessoa escolhe a entrevista e inicia-a no Virtual CV. |
practice:read |
Cada ferramenta tem o seu título (em inglês, como o assistente o mostra) e as suas anotações MCP, e tools/list indica as quinze (as três de entrevistas de prática só enquanto estão disponíveis); uma ferramenta para a qual a ligação não tem o âmbito responde forbidden_scope. As nove que só leem (list_cvs, get_cv, list_job_matches, get_job, list_applications, get_application_kit, list_practice_sessions, get_practice_report e start_practice) têm readOnlyHint: true. create_cv, duplicate_cv e save_job escrevem sem substituir nada (destructiveHint: false). update_cv_section, update_application e log_application podem substituir o que existia (registar de novo uma candidatura substitui o seu CV e a sua data), por isso têm destructiveHint: true e idempotentHint: true. As entradas são estritas: um argumento desconhecido é recusado antes de a ferramenta ser executada. url abre o CV no editor do Virtual CV.
Um Virtual CV está em linha: se o CV estiver publicado, update_cv_section altera de imediato a sua página pública. A descrição da ferramenta pede ao assistente que confirme com a pessoa antes de substituir uma secção.
Secções
As secções (sections) de um CV são fixas. Em update_cv_section, content é a secção inteira: um objeto para personal e summary, uma lista para as restantes. O que fica de fora é apagado, exceto o que é só de leitura, que se mantém.
| Secção | Contém |
|---|---|
personal |
headline, first_name, last_name, email, phone, location, right_to_work; identity_verified é só de leitura |
summary |
summary, short_summary, highlights |
experience |
funções: title, company, location, start_date, end_date, current, description, até três metrics (value, label); skills_used, verified e verified_by são só de leitura |
education |
institution, degree, field, location, start_date, end_date, current, description |
skills |
name, category, group; level é calculado pelo Virtual CV e é só de leitura |
languages |
name, proficiency |
awards |
prémios e certificações: name, category, date, issuer, description, credential_id, credential_url, expiry_date; verified é só de leitura |
projects |
name, category, contribution, blurb, description, location, start_date, end_date, current, metric |
interests |
uma lista de palavras |
social_links |
platform, url, username, visible |
references |
apenas name, só de leitura: os contactos das referências nunca são devolvidos e não podem ser escritos |
create_cv aceita as mesmas secções exceto references. Só aceita dados estruturados: não tem nenhum argumento de ficheiro, documento ou URL de ficheiro, e nunca importa, traduz nem adapta.
O que está verificado é só de leitura
Parte de um CV pode estar verificada: uma função num empregador que a pessoa verificou com o seu e-mail profissional, uma função com um endosso, um prémio que corresponde a uma certificação verificada com o Credly ou o Microsoft Learn e, depois de a sua identidade estar verificada, o seu nome próprio e apelido. get_cv assinala cada um (verified, verified_by, identity_verified).
- Uma entrada verificada tem de voltar sem alterações em
content, em qualquer posição. Alterada ou em falta, a atualização é recusada comverified_read_only. - Com a identidade verificada,
first_nameelast_namemantêm-se se ficarem de fora, e são recusados se forem diferentes. - Nada do que é escrito por MCP recebe um selo de verificado. Uma escrita cujo resultado mostraria um (uma função nova no empregador verificado, um prémio que corresponde a uma certificação verificada, um nome num CV novo depois de a identidade estar verificada) é recusada com
verification_not_allowed.duplicate_cvcopia as entradas verificadas tal como a aplicação, e na cópia continuam só de leitura.
Ofertas compatíveis
list_job_matches e get_job leem as compatibilidades que o Virtual CV já encontrou para a pessoa, tal como a sua página Vagas as mostra, e só as atuais: outra oferta é not_found. Nenhuma das duas faz uma nova pesquisa de compatibilidade, procura outras ofertas, lê um saldo ou chama um modelo. link é onde a pessoa se candidata: a página de candidatura de uma vaga do Orbit em www.wipperoz.com, ou o anúncio original. Nenhuma ferramenta se candidata. Para adaptar um CV a uma oferta, um assistente duplica o CV compatível (duplicate_cv) e altera a cópia com os dados da própria pessoa (update_cv_section).
O acompanhamento de candidaturas
save_job, log_application, update_application e list_applications escrevem e leem as entradas que a página Candidaturas da pessoa mostra, de imediato, com as mesmas verificações que a página.
- Uma oferta é um
titlee umacompany(até 200 caracteres cada) e, se quiser, umurl(https, até 2048; um parâmetro que pareça um início de sessão, como um token, um código, uma chave ou uma sessão, ou que tenha um endereço de e-mail, é removido antes de o guardar), osite(até 100; tirado do link, se for omitido) e umalocation(até 200). Nunca o texto do anúncio nem a conversa. log_applicationtransforma uma oferta guardada numa candidatura (applied; uma que já vá mais adiante mantém o estado), com a dataapplied_onou a de hoje, e dá-lhe umtracked_linkna primeira vez que tem um CV:https://wprz.me/e um código único dessa candidatura. O link abre a página pública do CV, e só enquanto esse CV estiver publicado (tracked_link_live); se não estiver,tracked_link_noteindica-o.- Uma abertura conta uma vez por visitante e por dia UTC, só no acompanhamento: nunca é registada como uma visualização do CV. Nunca contam um pedido
HEAD, um pré-carregamento ou uma pré-renderização do navegador, nem um pedido sem user agent ou com o de uma pré-visualização de links ou de um analisador de e-mail. Uma abertura quer dizer que alguém abriu o link, não que o empregador leu o CV. A pessoa recebe uma notificação e um e-mail na primeira abertura e, depois, no máximo um por dia para cada link, a menos que os desative. - Os estados são
saved,applied,interviewing,offer,rejectedewithdrawn. - As candidaturas feitas na Wipperoz, a uma vaga do Orbit, são listadas com
source: "orbit",read_only: trueestatus: "applied". É o empregador que as faz avançar, por issolog_applicationeupdate_applicationrespondemread_onlypara uma delas. - Nenhuma ferramenta elimina uma entrada. Uma pessoa pode ter até 2000 entradas; a partir daí,
save_jobrespondeapplication_limit.
O kit de candidatura
get_application_kit devolve os contactos da pessoa, o seu endereço de e-mail e o seu telefone, tal como os formulários os pedem, e só ao seu próprio assistente. get_cv também os mostra, na secção personal.
- Que CV:
cv_id, se for indicado; senão, o CV da candidatura (application_id); senão, o CV publicado mais recente ou, na falta dele, o mais recente.cv.chosen_becauseindica qual (requested,applicationoudefault). - Que carta de apresentação: uma das cartas desse CV escrita para
company, se existir. - Ficheiros: o PDF do CV e a carta de apresentação, cada um com um
status:ready,out_of_date(o CV ou a carta mudou depois de o PDF ser criado; o link mantém-se) ounot_generated(sem link: a pessoa descarrega-o uma vez na aplicação). Os links duram 10 minutos (expires_at). - A candidatura: com
application_id, o cargo, a empresa, o estado e o link de acompanhamento, para que o assistente dê ao empregador o link de acompanhamento em vez do habitual.
Só lê e nunca escreve: nenhuma ferramenta guarda uma resposta. A sua descrição pede ao assistente que preencha um formulário apenas com o kit, que nunca invente, que deixe à pessoa qualquer pergunta demográfica ou legal (origem étnica, género, deficiência, idade, religião, saúde, registo criminal) e que nunca envie o formulário nem passe ao passo seguinte sem indicação da pessoa.
Relatórios de entrevistas de prática
list_practice_sessions e get_practice_report leem, em texto, as sessões e os relatórios de entrevistas de prática da própria pessoa. Nunca devolvem uma gravação, áudio ou vídeo, nem a prática de outra pessoa. start_practice apenas cria um link: não cria nenhuma sessão nem cobra nada. A pessoa revê a função, escolhe a entrevista e inicia-a no Virtual CV, onde é gravada e o relatório é escrito. As três ferramentas só aparecem enquanto a prática é oferecida aos assistentes. Privacidade e gravações das entrevistas de prática explica quem vê o quê.
Erros
Uma ferramenta que não faz o que lhe foi pedido responde com um erro de ferramenta, isError: true, e error.code com uma frase que o assistente pode transmitir:
forbidden_scope: a ligação não tem o âmbito de que a ferramenta precisa;error.scopeindica-o.not_found: essa pessoa não tem esse CV, essa oferta, essa candidatura ou essa sessão de prática. Os de outra pessoa também sãonot_found.invalid_input: um argumento não serve;error.fieldindica qual.verified_read_only: a atualização alterou ou deixou de fora algo verificado;error.sectioneerror.itemsindicam o quê.verification_not_allowed: a escrita teria mostrado um selo de verificado em algo escrito pelo assistente;error.itemsindica em quê.cv_limit: a pessoa já temerror.max_cvsCVs.read_only: a candidatura foi feita na Wipperoz, e só o empregador a faz avançar.application_limit: a pessoa já acompanhaerror.maxcandidaturas.report_not_ready: o relatório de prática ainda está a ser preparado; tente novamente dentro de alguns minutos.internal_error: nada foi alterado; tente novamente.
A camada HTTP responde com um erro JSON-RPC:
| Estado | error.code |
Quando |
|---|---|---|
401 |
-32001 |
Sem início de sessão no Virtual CV, com um que foi desligado ou expirou, ou com uma chave do Orbit. WWW-Authenticate indica onde iniciar sessão. |
405 |
-32000 |
Um método que não é POST. |
429 |
-32029 |
Um limite foi ultrapassado (abaixo). error.data tem window, limit, resets_at e retry_after_seconds. |
400 |
-32700 |
O corpo não é JSON. |
500 |
-32603 |
O servidor não conseguiu responder. |
Limites
Cada pessoa tem, por predefinição:
- 60 pedidos por minuto. Cada pedido conta um, exceto uma chamada a uma ferramenta, que conta como indicado abaixo.
- 500 unidades por dia, contadas só nas chamadas a ferramentas: uma leitura conta uma e uma escrita duas. As escritas são
create_cv,update_cv_section,duplicate_cv,save_job,log_applicationeupdate_application. O dia é reposto às 00:00 UTC. - 10 CVs:
create_cveduplicate_cvsão recusadas comcv_limitquando a pessoa já tem esse número.
Acima de um limite, o servidor responde 429 com X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After, e a mensagem diz quando é reposto. Uma chamada recusada pelo limite diário não conta.
O que nunca faz
- Gastar créditos. Todas as ferramentas são gratuitas: nenhuma lê um saldo, cobra ou chama um modelo.
- Candidatar-se por alguém. Nenhuma ferramenta envia uma candidatura nem contacta um empregador: os links são abertos pela pessoa.
- Eliminar ou publicar. Nenhuma ferramenta elimina um CV nem uma candidatura, nem publica um CV ou o deixa offline.
- Importar um ficheiro. Um PDF é importado na aplicação do Virtual CV, onde a IA da Wipperoz o lê.
- Partilhar dados de outras pessoas. Nenhuma ferramenta devolve contactos de referências, quem deu um endosso, o CV ou as candidaturas de outra pessoa nem identificadores internos além de
cv_id,job_ideapplication_id. - Chegar a outra pessoa. Todas as ferramentas trabalham nos dados de quem iniciou sessão.