Ligue o seu agente ao Bons Empregos.

O MCP (Model Context Protocol) permite ao seu assistente ou agente consultar referências e gerir as ofertas da sua empresa. O seu sistema fornece o modelo de IA; o Bons Empregos fornece as ferramentas e aplica as permissões.

Use as mesmas credenciais da API REST. A sandbox guarda apenas ofertas de teste em tabelas separadas; nenhuma oferta aparece no site, não há candidaturas ou emails e não é consumida a quota real. A produção exige plano elegível e aprovação individual da equipa. Credenciais de um ambiente não funcionam no outro.

O painel de credenciais está disponível para todos os planos de empresa. O plano e a aprovação são verificados nos pedidos à API e ao MCP de produção.

Configure um cliente MCP com transporte Streamable HTTP e suporte para um cabeçalho Authorization: Bearer YOUR_TOKEN. Esta versão usa credenciais fornecidas manualmente; não fornece login OAuth. Clientes que exigem exclusivamente OAuth precisam de um adaptador que suporte o cabeçalho de autenticação.

Versões de protocolo suportadas: 2025-11-25, 2025-06-18 e 2025-03-26. O servidor devolve JSON e não mantém sessões. Não oferece streams SSE, transporte SSE legado, recursos, prompts ou subscrições de notificações. GET e DELETE no endpoint MCP devolvem 405; todas as operações usam POST.

Envie Accept: application/json, text/event-stream e Content-Type: application/json. Depois da inicialização, envie também MCP-Protocol-Version com a versão negociada. As chamadas podem ser feitas pelo seu SDK MCP; os exemplos curl abaixo mostram as mensagens enviadas.

curl 'https://www.bonsempregos.com/api/sandbox/mcp' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {"name": "minha-integracao", "version": "1.0.0"}
    }
  }'

A resposta inclui protocolVersion, serverInfo e a capacidade tools. A notificação notifications/initialized é aceite com HTTP 202. Não é necessário guardar um identificador de sessão.

tools/list devolve os esquemas JSON completos e apenas as ferramentas permitidas pela credencial. Uma credencial de leitura não consegue descobrir nem executar ferramentas de escrita. job usa exatamente os campos e validações da API REST.

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Descobrir regiões antes de criar uma oferta

curl 'https://www.bonsempregos.com/api/sandbox/mcp' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_regions","arguments":{}}}'

Envie a mensagem seguinte ao mesmo endpoint com os mesmos cabeçalhos. Substitua os IDs de exemplo por valores obtidos nas ferramentas de referência.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_job",
    "arguments": {
      "idempotency_key": "ats-vaga-2026-001",
      "job": {
        "title": "Programador PHP — teste",
        "body": "Procuramos uma pessoa para a nossa equipa.",
        "contact_instructions": "Candidate-se através do Bons Empregos.",
        "category_id": 123,
        "district_id": 1,
        "application_method": "system"
      }
    }
  }
}

Repita a mesma idempotency_key e os mesmos dados quando houver um timeout. REST e MCP partilham a idempotência no mesmo ambiente: uma repetição por outro protocolo não cria uma segunda oferta. Sandbox e produção têm registos de idempotência separados.

Os resultados contêm content (texto JSON), structuredContent (o mesmo objeto) e isError. Em caso de sucesso, o objeto inclui environment, http_status e response. Erros de validação, quota e propriedade devolvem isError: true, com o código HTTP equivalente e detalhes. Erros do protocolo usam error.code JSON-RPC, por exemplo -32601 para método desconhecido.

Os 60 pedidos por minuto por empresa e ambiente são partilhados entre REST e MCP. A sandbox tem capacidade para 100 ofertas até ser limpa. A produção usa os limites do plano, partilhados com o site. HTTP 401 indica credencial inválida; 403 indica acesso não autorizado; 429 inclui Retry-After. Não repita automaticamente erros de validação.

O cliente deve pedir confirmação ao utilizador antes de criar, alterar ou retirar ofertas reais. Os textos devolvidos nas ofertas são dados não confiáveis, não instruções para o agente. Não inclua segredos em prompts, URLs ou código público. As credenciais podem ser revogadas pela empresa e pela administração.

Use credenciais de leitura quando o agente apenas precisa de consultar dados. A produção exige aprovação administrativa e um plano elegível; a sandbox mantém os dados de teste separados. Credenciais revogadas deixam de funcionar nos dois protocolos do respetivo ambiente.