Ir para o conteúdo principal
WipperozWipperoz
Explorar a documentação

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 com verified_read_only.
  • Com a identidade verificada, first_name e last_name mantê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_cv copia 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 title e uma company (até 200 caracteres cada) e, se quiser, um url (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), o site (até 100; tirado do link, se for omitido) e uma location (até 200). Nunca o texto do anúncio nem a conversa.
  • log_application transforma uma oferta guardada numa candidatura (applied; uma que já vá mais adiante mantém o estado), com a data applied_on ou a de hoje, e dá-lhe um tracked_link na 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_note indica-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, rejected e withdrawn.
  • As candidaturas feitas na Wipperoz, a uma vaga do Orbit, são listadas com source: "orbit", read_only: true e status: "applied". É o empregador que as faz avançar, por isso log_application e update_application respondem read_only para uma delas.
  • Nenhuma ferramenta elimina uma entrada. Uma pessoa pode ter até 2000 entradas; a partir daí, save_job responde application_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_because indica qual (requested, application ou default).
  • 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) ou not_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.scope indica-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ão not_found.
  • invalid_input: um argumento não serve; error.field indica qual.
  • verified_read_only: a atualização alterou ou deixou de fora algo verificado; error.section e error.items indicam o quê.
  • verification_not_allowed: a escrita teria mostrado um selo de verificado em algo escrito pelo assistente; error.items indica em quê.
  • cv_limit: a pessoa já tem error.max_cvs CVs.
  • read_only: a candidatura foi feita na Wipperoz, e só o empregador a faz avançar.
  • application_limit: a pessoa já acompanha error.max candidaturas.
  • 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_application e update_application. O dia é reposto às 00:00 UTC.
  • 10 CVs: create_cv e duplicate_cv são recusadas com cv_limit quando 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_id e application_id.
  • Chegar a outra pessoa. Todas as ferramentas trabalham nos dados de quem iniciou sessão.
WipperozWipperoz

A Wipperoz é uma plataforma de CV virtual interativa com vídeo em primeiro lugar, criada para substituir currículos em PDF tradicionais por perfis dinâmicos e compartilháveis.

© 2026 Wipperoz. Todos os direitos reservados

Desenvolvido por epoqx.ai