WorkforceGPT.AI MCP

WorkforceGPT para agentes

Um servidor MCP que permite que qualquer agente compatível avalie uma descrição de vaga e construa um perfil de cargo estruturado (responsabilidades e habilidades com níveis de proficiência) em nome de alguém com uma conta WorkforceGPT. Conecte-o em uma etapa, sem chave de API. Nos aplicativos Claude, ele está no diretório de conectores.

URL do servidor https://workforcegpt.ai/mcp

Início rápido

Quatro etapas, e as três primeiras não envolvem código algum. Ao final da etapa dois, você terá avaliado uma descrição de vaga real apenas pedindo em inglês simples. A etapa quatro é para quando você quiser que isso aconteça da mesma forma todas as vezes.

Você precisa de duas coisas: uma conta WorkforceGPT, que é gratuita para criar e precisa de um endereço de e-mail verificado, e uma cópia do Claude (ou qualquer outro cliente MCP).

1

Conecte o Claude ao servidor

Nos aplicativos Claude, você pode adicionar o WorkforceGPT pelo diretório de conectores, ou seja, sem colar nada. Em qualquer outro lugar, você entrega ao seu cliente a URL na caixa acima. De qualquer forma, não há chave de API nem ID de cliente para solicitar antecipadamente, porque seu cliente se registra na primeira vez que se conecta.

Claude web, desktop ou Cowork

O WorkforceGPT está listado no diretório de conectores do Claude. Abra Configurações, vá em Conectores, navegue pelo diretório e adicione WorkforceGPT. Não há URL para copiar neste caminho.

Não está vendo? A disponibilidade do diretório depende do seu plano, e você sempre pode usar o caminho manual: escolha Adicionar conector personalizado, dê o nome que quiser e cole a URL do servidor da caixa acima. Esse também é o caminho a usar se você estiver apontando para sua própria implantação deste servidor em vez da nossa. Ambos terminam na mesma tela de login.

Esse menu pertence à Anthropic e pode mudar. O guia deles sobre conectores é a versão que permanece atual, incluindo em quais planos cada caminho está disponível.

Claude Code

Adicione uma vez e depois faça login:

claude mcp add --transport http workforcegpt https://workforcegpt.ai/mcp

Execute /mcp dentro do Claude Code para concluir o login e claude mcp list para confirmar que está conectado.

Qualquer outro cliente MCP

Dê a URL e nada mais. O servidor publica os documentos de descoberta padrão, então um cliente que fala OAuth encontra o resto sozinho. O detalhe está em como a conexão funciona.

Qualquer que seja o caminho escolhido, uma janela do navegador abre e pede que você faça login no WorkforceGPT e aprove a conexão. A tela nomeia o aplicativo que está solicitando, o endereço da web para onde a aprovação será enviada e exatamente o que está sendo pedido. Leia o do meio: é a única coisa que um aplicativo não pode falsificar sobre si mesmo.

A partir daí, o agente age como você, contra sua conta e seu saldo. Você pode desconectá-lo quando quiser pela página de configurações, e isso tem efeito imediato.

Se o navegador não voltar. Levá-lo a um navegador é uma etapa do Claude, não nossa, e ela acontece antes de este servidor ser contatado. Então, se você cair em uma tela de login do Claude em vez da do WorkforceGPT, ou se a aprovação parecer ter funcionado e o conector ainda aparecer como desconectado, verifique se seu navegador está conectado à mesma conta do Claude que o aplicativo que você está usando. Uma incompatibilidade interrompe a transferência cedo e parece exatamente um servidor que não autentica você.

2

Peça algo

Não há sintaxe para aprender. O Claude lê as descrições das ferramentas e escolhe uma. Experimente qualquer uma destas:

"Aqui está uma descrição de vaga que vamos publicar. Avalie e me diga o que corrigir." (depois cole-a) Chama assess_job_description e responde na hora, com uma pontuação, o que a pontuação significa e o que fazer a respeito.

"Crie um perfil de cargo para um Analista de Dados Sênior na Northwind." Chama generate_role, que inicia o trabalho e devolve um ID, depois verifica até terminar. Veja como a geração se comporta.

"Quanto me resta na minha conta WorkforceGPT?" Chama get_account_status. Vale a pena perguntar antes de planejar um lote de trabalho, em vez de depois.

Se algo for recusado, a resposta diz qual limite você atingiu e o que resta na conta, em palavras, em vez de fazer o agente adivinhar por um código de status.

3

Adicione as duas Skills prontas

Uma Skill é um arquivo Markdown de instruções que o Claude carrega quando uma conversa pede. Enviamos duas. Elas não adicionam capacidade: tudo o que fazem, você acabou de fazer sem elas na etapa dois.

O que elas adicionam é julgamento, ou seja, as partes para as quais uma descrição de ferramenta não tem espaço. Quando vale a pena chamar uma ferramenta? Como gastar bem um saldo pequeno? Como transformar o título interno de uma empresa em um que o mercado de trabalho reconheça? E o que importance_to_role: 1 significa? Significa Alto, que é o oposto do que parece.

assess-job-description

Avaliar uma descrição de vaga existente e decidir o que fazer com a pontuação.

build-role-profile

Gerar um perfil de cargo e acertar o título para que a correspondência com o mercado de trabalho funcione.

No Claude Code

Cada skill é um SKILL.md em uma pasta com o nome dela:

SRC=https://workforcegpt.ai/mcp/skills
DEST=~/.claude/skills

for s in assess-job-description build-role-profile; do
  mkdir -p $DEST/$s && curl -s $SRC/$s.md -o $DEST/$s/SKILL.md
done

Use .claude/skills/ dentro de um projeto se quiser que ela viaje com o repositório em vez de seguir você.

Nos aplicativos Claude

Baixe cada arquivo dos links acima, coloque-o em uma pasta com o nome da skill como SKILL.md, compacte essa pasta e envie-a nas configurações do Claude. O guia de Agent Skills da Anthropic tem o caminho atual e quais planos ele exige.

Nada mais precisa delas. Um agente que não é o Claude lê a mesma orientação do description e do inputSchema de cada ferramenta, que é onde ficam as partes não opcionais.

4

Escreva sua própria Skill

Você não precisa ser desenvolvedor para isso e não precisa começar do zero. As duas skills acima já lidam com os problemas gerais difíceis. O que elas não podem saber é como sua organização faz isso: suas famílias de cargos, seu nivelamento, seu formato padrão, a etapa de aprovação que você quer antes de qualquer coisa ser registrada.

Então a skill que vale a pena escrever é uma fina que envolve as nossas. Aqui está um exemplo completo. Salve-o como SKILL.md em uma pasta chamada northwind-role-profiles, no mesmo lugar onde você colocou as duas acima.

---
name: northwind-role-profiles
description: Create a role profile that follows Northwind's job architecture conventions. Use when someone asks for a job profile, role definition, competency model or skills framework for a Northwind position, or wants an existing job description turned into one.
---

# Northwind role profiles

Our job architecture has rules WorkforceGPT does not know about. Apply them
around the tools, not instead of them.

## Before spending anything

Call \`get_account_status\` and tell the person what the account has left. Do
not guess the allowance, it is configurable and this file will not be updated
when it changes.

## Getting the title right

We title roles internally like "Staff Engineer II, Payments Platform". That
will not match labor-market data and the generation will come back thin. Send
the occupation instead, i.e. "Software Engineer", and keep our internal title
for the heading you write at the end.

If the person insists on the internal title, pass the old job description as
\`job_description\` and set \`use_job_description_if_title_not_found\` to true, so
there is something to build from when the title does not match.

## Generating

Call \`generate_role\` with \`role_title\` and \`company_name\`. It returns a
\`role_id\` rather than a profile. Poll \`check_role_status\` with that id until
\`status\` is no longer \`pending\`.

## Reading the result

\`importance_to_role\` is 1 for High, 2 for Medium and 3 for Low. It reads like
the opposite of what it means, so print the label and never the number.

## What to hand back

A table of responsibility, skill and proficiency level, then ask whether to
add it to the job architecture sheet. Never add it without being asked.

As quatro coisas que decidem se funciona

1. A descrição é o gatilho. Até o Claude decidir abrir o arquivo, ele só vê o nome e a descrição, então escreva a descrição sobre as situações em que alguém estará, não sobre o que o arquivo contém. "Use quando alguém pedir um perfil de cargo…" vence "Ferramentas para perfis de cargo".
2. Nomeie as ferramentas exatamente. generate_role, não "a ferramenta de geração". Os nomes estão em a lista de ferramentas e são o que o agente precisa digitar.
3. Não escreva o saldo no arquivo. Ele é configurável, e um arquivo no seu laptop não é reimplantado quando muda. Aponte para get_account_status em vez disso, que está sempre certo.
4. Diga o que fazer com a resposta. Uma pontuação sem interpretação anexada é uma pontuação que um agente interpretará generosamente. Diga o que é bom e o que fazer com o ruim.

Verificando se carregou

Comece uma nova conversa e diga algo que deva acioná-la, sem nomear a skill. Se o Claude não a usar, o problema é a descrição, não o corpo: ela precisa soar como a coisa que a pessoa realmente pediu.

Referência

O detalhe abaixo do início rápido: cada ferramenta e seus argumentos, o que os escopos significam, como os limites funcionam e o próprio protocolo.

Ferramentas

10 ferramentas. O escopo ao lado de cada uma é o que seu cliente precisa ter recebido para chamá-la; uma chamada sem ele retorna um erro de ferramenta nomeando o escopo necessário.

assess_job_description

assess

Avalie uma descrição de vaga de 0 a 100 sobre o quão limpa ela pode ser transformada em um perfil de cargo estruturado e diga o que está faltando e o que corrigir. Recebe a descrição da vaga como texto. Executa de forma síncrona — a resposta volta na mesma solicitação — então permita um tempo limite generoso no cliente. Medido: veja get_account_status.

check_role_status

read

Verifique se uma geração de cargo terminou e retorne o perfil completo do cargo quando terminar. Faça polling após generate_role.

generate_role

generate

Comece a gerar um perfil de cargo estruturado — descrição, responsabilidades, habilidades com níveis de proficiência. Retorna imediatamente com um role_id; a geração continua em segundo plano, então faça polling em check_role_status. Gasta um dos créditos de geração de cargo desta conta. Apenas uma geração roda por vez.

get_account_status

read

Informe a qual conta WorkforceGPT esta credencial pertence, o que ela tem permissão para fazer e quanto da cota resta. Chame primeiro: é assim que você descobre se uma geração será aceita antes de construí-la.

get_assessment

read

Busque uma avaliação de descrição de vaga executada anteriormente pelo ID.

get_public_role

sem necessidade de conta

Busque um perfil de cargo publicado da biblioteca pública por completo. Não precisa de conta.

get_role

read

Busque um perfil de cargo gerado por completo: descrição, responsabilidades, habilidades com níveis de proficiência e os cursos sugeridos por habilidade quando a geração os pediu.

list_my_assessments

read

Liste as avaliações recentes de descrição de vaga desta conta, das mais novas para as mais antigas, tanto desta API quanto do aplicativo web.

list_my_roles

read

Liste os perfis de cargo desta conta, dos mais novos para os mais antigos.

search_public_roles

sem necessidade de conta

Pesquise a biblioteca pública de cargos do WorkforceGPT — perfis de cargo que seus autores escolheram publicar. Não precisa de conta. Use para exemplos de como um perfil gerado se parece ou para referências anteriores sobre um título.

Cada ferramenta declara seus argumentos como JSON Schema, servido literalmente como o inputSchema do MCP, para que seu cliente possa ler os tipos e os campos obrigatórios em vez de adivinhá-los pela prosa.

Exemplos práticos

Estes são objetos de argumento, ou seja, o que vai no arguments de um tools/call, ou no corpo no caminho HTTP simples. Se você está dirigindo o Claude em vez de escrever um cliente, nunca vai digitar isso: estão aqui para você ver o que o agente está realmente enviando.

Avaliar uma descrição de vaga

{
  "job_description": "Senior Data Analyst\n\nNorthwind is hiring an analyst to own reporting for the commercial team...",
  "filename": "senior-data-analyst.txt"
}

Iniciar um perfil de cargo

{
  "role_title": "Data Analyst",
  "company_name": "Northwind",
  "job_description": "Senior Data Analyst\n\nNorthwind is hiring an analyst to own reporting for the commercial team...",
  "use_job_description_if_title_not_found": true,
  "include_learning_resources": true,
  "learning_resources_source": "Skillsoft"
}

Apenas role_title e company_name são obrigatórios. O resto é mostrado aqui porque são os que valem a pena conhecer: a descrição da vaga é o que salva uma geração quando o título não corresponde aos dados do mercado de trabalho, e os recursos de aprendizado são o único lugar onde este servidor oferece uma escolha de fonte.

Verificar

{ "role_id": 4812 }

Navegar pela biblioteca pública

{ "query": "project manager", "limit": 5 }

Este e get_public_role leem o corpus publicado em /roles/. Não custam nada contra o saldo de uma conta e, no caminho HTTP simples, não precisam de credencial alguma.

Escopos

Três, e são o que a tela de consentimento mostra à pessoa que aprova seu cliente. Peça apenas o que você precisa: um cliente solicitando generate está pedindo para gastar os créditos de alguém, e eles podem ver isso.

read

Veja seus cargos gerados e avaliações de descrição de vaga

assess

Avalie descrições de vaga em seu nome

generate

Gere perfis de cargo em seu nome, usando seus créditos

Como a geração se comporta

generate_role não retorna um perfil de cargo. Ele inicia um e retorna um role_id. Faça polling em check_role_status com esse ID, a cada 30 segundos aproximadamente em vez de continuamente, até o status sair de pending.

Quanto tempo isso leva depende do cargo e da carga, e preferimos não dar um número que não podemos cumprir. O que podemos dizer é o teto: uma geração ainda em execução após 60 minutos é marcada como falha, e uma geração falha não gasta um crédito.

Apenas uma geração roda por conta por vez. Iniciar uma segunda enquanto uma está em andamento retorna generation_in_progress em vez de enfileirar.

O que volta

Uma vez que o status seja completed, tanto check_role_status quanto get_role carregam um array result. Cada entrada é um perfil de função, com a descrição, as responsabilidades, as habilidades (cada uma com sua importância, seu nível de proficiência exigido e os indicadores comportamentais para cada nível).

Uma coisa para saber sobre esse objeto: é a forma própria do mecanismo de geração, passada adiante em vez de reescrita, com uma única exceção. Os cursos sugeridos são normalizados na saída, então um curso é lido aqui da mesma forma que é lido em get_public_role:

result[0].skills[0].learning_resources[0] = {
  "title":       "Analyzing Data with Power BI",
  "provider":    "Skillsoft",
  "year":        "2024",
  "description": "...",
  "url":         "https://..."
}

Eles estão lá por padrão. Passe include_learning_resources: false para generate_role para um perfil mais curto quando ninguém for agir sobre as sugestões de treinamento, e learning_resources_source para escolher o catálogo. Leia o campo defensivamente: uma habilidade sem nada a sugerir, ou um perfil gerado sem elas, carrega uma lista vazia ou nenhuma chave. Nenhum dos casos é um erro.

assess_job_description é o contrário: ele roda de forma síncrona e responde na mesma requisição. Ele faz trabalho real, então dê à chamada um timeout generoso de cliente em vez dos poucos segundos padrão.

Limites

Cada recusa informa qual limite você atingiu, o que resta na conta e onde obter mais. Você não deve precisar descobrir isso a partir de um código de status.

Gerações de funções

3 por conta

Avaliações de descrições de cargos por esta API

3 por conta

Gerações simultâneas

1

Avaliações executadas pelo aplicativo web são gratuitas e sem medição; apenas as da API são contadas, porque um agente pode fazer loop onde uma pessoa clicando em um botão não faz. Publicar uma função gerada na biblioteca pública concede à conta uma geração extra, mas publicar é uma ação do aplicativo web. Veja o que ele não fará.

Chame get_account_status antes de planejar o trabalho. Ele retorna o mesmo bloco de cota que toda recusa carrega, para que você possa descobrir que não tem mais nada antes de construir uma requisição, em vez de depois.

Quando uma conta fica sem cota

Ainda não há recarga por autoatendimento. Fale com a TalentGuard e resolveremos isso.

O que este servidor deliberadamente não fará

Publicar qualquer coisa. Funções podem ser publicadas em uma biblioteca pública indexada por busca em /roles/, sob o nome do titular da conta, se ele escolher. Essa é uma decisão sobre a pegada pública de alguém, e não é uma que um agente possa tomar de forma significativa em nome dele, então não há ferramenta para isso e nenhum escopo que permitiria. A publicação acontece no aplicativo web ou não acontece.

Tocar em uma conta ou nos dados de qualquer outra pessoa. Nenhuma ferramenta exclui, nenhuma ferramenta envia e-mails, nenhuma ferramenta alcança funções administrativas. Uma credencial resolve para exatamente uma conta e vê apenas o que essa conta possui.

Aceitar arquivos. Os argumentos das ferramentas MCP são JSON, então uma descrição de cargo chega como texto. Se você estiver segurando um PDF ou DOCX, envie seu texto com cada título e cada item de lista em uma linha própria. Markdown não é necessário. O que importa são as quebras de linha: texto unido em um parágrafo é avaliado como um bloco de prosa, porque foi isso que chegou.

Como a conexão funciona

O primeiro passo do início rápido é toda a configuração. Isto é o que acontece por baixo, o que importa se você está escrevendo um cliente em vez de usar um.

O servidor implementa OAuth 2.1. A primeira requisição do seu cliente é recusada com um 401 carregando um cabeçalho WWW-Authenticate que aponta para https://workforcegpt.ai/.well-known/oauth-protected-resource. A partir daí, ele encontra o servidor de autorização, registra-se (o registro dinâmico de cliente RFC 7591 está aberto, por isso não há chave para colar) e envia a pessoa que o usa para uma tela de consentimento. PKCE é exigido para todo cliente, incluindo os confidenciais.

A autenticação é exigida para toda mensagem, incluindo initialize. Isso é deliberado: o 401 é como um cliente dado apenas uma URL encontra todo o resto, então ele tem que ser a primeira coisa que um cliente novo vê.

A pessoa que aprova a tela de consentimento deve ter uma conta WorkforceGPT com endereço de e-mail verificado. O agente então age como ela, contra a cota dela.

Se o seu cliente não suportar descoberta OAuth

Aponte-o diretamente para estes:

Protected resource  https://workforcegpt.ai/.well-known/oauth-protected-resource
Authorization server https://workforcegpt.ai/.well-known/oauth-authorization-server
MCP endpoint         https://workforcegpt.ai/mcp  (POST, JSON-RPC 2.0)

Revisões de protocolo suportadas: 2025-11-25, 2025-06-18, 2025-03-26. Se a sua for mais nova, initialize negocia em vez de recusar: ele responde com a mais recente que falamos e você decide se continua. Todo outro método responde a um cabeçalho MCP-Protocol-Version que não conhecemos com um 400 nomeando o que falamos, que é o que a especificação de transporte pede. ⚠️ O 401 sempre vem primeiro, então um cliente em uma revisão à frente da nossa ainda pode descobrir como entrar. O servidor é sem estado, ou seja, ele não emite Mcp-Session-Id, e não oferece fluxo iniciado pelo servidor, então um GET pedindo text/event-stream é respondido 405. O mesmo vale para DELETE, já que não há sessão para encerrar.

Métodos: initialize, ping, tools/list, tools/call e notifications/*, que são reconhecidos e não respondidos. Apenas tools é anunciado sob capacidades, com listChanged: false, porque o conjunto de ferramentas é fixo quando o servidor inicia.

Uma chamada de ferramenta recusada é um resultado, não um erro de protocolo. Uma cota gasta, um id desconhecido, um argumento ruim ou um escopo ausente todos retornam como isError: true com o motivo em structuredContent, porque o protocolo funcionou e o agente precisa ler o porquê. Apenas um nome de ferramenta desconhecido ou params malformado é um erro JSON-RPC. Trate o primeiro tipo como uma falha de transporte e você esconderá a mensagem que diz o que fazer a seguir.

Sem um cliente MCP

As mesmas ferramentas são acessíveis por HTTP comum se você estiver construindo algo que não fala MCP. Mesma credencial, mesmas cotas, mesmas respostas: POST https://workforcegpt.ai/api/v1/mcp/tools/<name> com um objeto JSON de argumentos.

curl -s https://workforcegpt.ai/api/v1/mcp/tools \
  | jq '.tools[] | {name, scope}'

curl -s -X POST https://workforcegpt.ai/api/v1/mcp/tools/get_account_status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{}'

As duas ferramentas de biblioteca pública (search_public_roles e get_public_role) não precisam de credencial alguma neste caminho. Elas leem o mesmo corpus que os mecanismos de busca já indexam, então você pode ver como é um perfil de função finalizado antes de qualquer um se cadastrar em qualquer coisa. Este aqui roda como está:

curl -s -X POST https://workforcegpt.ai/api/v1/mcp/tools/search_public_roles \
  -H "Content-Type: application/json" \
  -d '{"query": "project manager", "limit": 5}'

Pelo MCP em si, toda ferramenta precisa de um token, incluindo essas duas. É isso que mantém o bootstrap 401 intacto, e um cliente que se conectou tem um token de qualquer forma.

Uma conta é gratuita para criar e vem com 3 gerações de funções.

Privacidade