Job Opportunities API (JOA)

npx add-mcp 'https://api.jobopportunitiesapi.org/mcp'

Servidor MCP JOA

Servidor remoto Model Context Protocol para a Job Opportunities API (JOA) — pesquise vagas ao vivo publicadas diretamente por empregadores nos próprios sites de carreira das empresas, consulte o sinal de contratação de uma empresa, leia estatísticas agregadas de mercado e acompanhe o feed incremental de alterações, direto de um agente de IA.

• Endpoint ao vivo: https://api.jobopportunitiesapi.org/mcp (HTTP Streamable, endpoint único, ambos os verbos)
• Documentação: https://jobopportunitiesapi.org/mcp
• Preços: https://jobopportunitiesapi.org/pricing
• Registro: org.jobopportunitiesapi/mcp no Registro MCP oficial
• Este repositório: apenas metadados de listagem/configuração — nenhum código-fonte da API. O servidor em si é distribuído no binário da API Go da própria JOA.

As seis ferramentas

Ferramenta	O que faz	Chave necessária?
search_jobs	Filtra o registro ao vivo por país, cidade, estado dos EUA, categoria, senioridade, tipo de remoto, tipo de emprego, salário, empregador, tipo de fonte, texto livre	Sim
get_job	Detalhes completos de uma vaga, incluindo o texto completo do anúncio e informações de encerramento	Sim
company_hiring	Perfil de um empregador e tendência de vagas abertas em várias janelas de tempo	Tendência sem chave; perfil completo/lista exige chave
market_signals	Percentis de salário agregados e tempo para preencher por família de cargo × país × senioridade	Não
coverage	Tamanho do conjunto de dados, atualização, auditoria de cobertura por país e principais empregadores	Não
changes_since	Feed incremental de deltas: criadas/atualizadas/retiradas/removidas desde um cursor	Sim, plano Growth ou superior

Uma ferramenta de serviço de linhas chamada sem chave nunca toca o banco de dados — ela retorna uma recusa estruturada indicando a página da chave gratuita, nunca um 401 simples. Qualquer texto de descrição de vaga ou empresa retornado por qualquer ferramenta é texto de terceiros extraído de um site externo do empregador: a descrição de cada ferramenta instrui o modelo chamador a tratar esse conteúdo como dados, nunca como uma instrução a ser seguida.

Autenticação

Exatamente uma porta: um cabeçalho HTTP Authorization: Bearer <key> na conexão MCP — nunca um parâmetro de consulta ?key=, nunca um argumento de ferramenta. Uma chave gratuita Explore (1.000 registros/mês, sem cartão) é suficiente para testar todas as ferramentas com chave: https://jobopportunitiesapi.org/login?ref=mcp

Cada chamada de ferramenta é medida de forma idêntica ao endpoint REST que ela encapsula — mesmo plano, mesma cota mensal, mesmo limite de taxa. changes_since exige o plano Growth ou superior, assim como /v1/changes.

Configuração do cliente

Claude Desktop / Claude.ai (conector personalizado)

Configurações → Conectores → Adicionar conector personalizado, ou cole em claude_desktop_config.json:

{
  "mcpServers": {
    "joa": {
      "type": "streamableHttp",
      "url": "https://api.jobopportunitiesapi.org/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor

.cursor/mcp.json do projeto ou global:

{
  "mcpServers": {
    "joa": {
      "url": "https://api.jobopportunitiesapi.org/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Windsurf

Cascade → Plugins → Servidores MCP → adicione um servidor personalizado com a URL e o cabeçalho acima, ou edite ~/.codeium/windsurf/mcp_config.json diretamente (mesma estrutura JSON do Cursor).

VS Code

Paleta de Comandos → "MCP: Adicionar Servidor" → HTTP, ou adicione a .vscode/mcp.json usando a mesma estrutura JSON mostrada para o Cursor acima.

Cline

Servidores MCP → Configurar Servidores MCP, mesma estrutura JSON do Cursor acima (o Cline lê o bloco mcpServers idêntico).

ChatGPT (modo desenvolvedor / Apps)

O diretório unificado de plugins da OpenAI exige um envio em ZIP com uma conta de desenvolvedor com identidade verificada e um desafio de propriedade de domínio — ainda não enviado. Até lá, qualquer cliente MCP em modo desenvolvedor do ChatGPT que aceite uma URL HTTP Streamable bruta com um cabeçalho estático pode usar a configuração mostrada acima.

JSON-RPC bruto (curl)

Handshake:

curl -s https://api.jobopportunitiesapi.org/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

Uma chamada de ferramenta:

curl -s https://api.jobopportunitiesapi.org/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_jobs","arguments":{"country":["DE"],"category":["Engineering"]}}}'

Metadados do registro

mcp/server.json é a entrada publicada no Registro MCP oficial sob o namespace verificado por DNS org.jobopportunitiesapi/mcp.

Sobre a JOA

Job Opportunities API — vagas ao vivo publicadas diretamente por empregadores, extraídas dos próprios sites de carreira e sistemas de rastreamento de candidatos das empresas, com vagas encerradas mantidas com datas de fechamento. Cada campo é marcado como publicado/inferido/ausente (proveniência); lacunas de cobertura são publicadas, não ocultadas (números ao vivo: https://jobopportunitiesapi.org/facts). API REST, estatísticas sem chave, páginas web de vagas/empresas, exportação CSV, especificação OpenAPI.

• Site: https://jobopportunitiesapi.org
• Documentação: https://jobopportunitiesapi.org/docs
• Preços: https://jobopportunitiesapi.org/pricing
• Contato: support@jobopportunitiesapi.org

Licença

O conteúdo deste repositório (documentação, trechos de configuração e server.json) é licenciado sob a Licença MIT. Este repositório não contém código-fonte da API JOA ou da implementação do servidor MCP — esses vivem no monorepo privado da JOA e são distribuídos como parte do binário de produção da API.