Job Opportunities API (JOA)

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

Servidor MCP de JOA

Servidor remoto de Model Context Protocol para la Job Opportunities API (JOA) — busca ofertas de empleo en vivo publicadas directamente por empleadores en sus propios sitios de carrera, consulta la señal de contratación de una empresa, lee estadísticas agregadas del mercado y sigue el feed de cambios incrementales, directamente desde un agente de IA.

• Endpoint en vivo: https://api.jobopportunitiesapi.org/mcp (HTTP Streamable, endpoint único, ambos verbos)
• Documentación: https://jobopportunitiesapi.org/mcp
• Precios: https://jobopportunitiesapi.org/pricing
• Registro: org.jobopportunitiesapi/mcp en el Registro MCP oficial
• Este repositorio: solo metadatos de listado/configuración — sin código fuente de la API. El servidor en sí se distribuye en el binario de la API de Go de JOA.

Las seis herramientas

Herramienta	Qué hace	¿Requiere clave?
search_jobs	Filtra el registro en vivo por país, ciudad, estado de EE. UU., categoría, nivel de seniority, tipo remoto, tipo de empleo, salario, empleador, tipo de fuente, texto libre	Sí
get_job	Detalle completo de una oferta de empleo, incluido el texto completo del anuncio e información de cierre	Sí
company_hiring	Perfil de un empleador y tendencia de roles abiertos en varias ventanas de tiempo	La tendencia no requiere clave; el perfil completo/lista de roles requiere clave
market_signals	Percentiles de salario agregados y tiempo de contratación por familia de empleo × país × seniority	No
coverage	Tamaño del conjunto de datos, frescura, auditoría de cobertura por país y principales empleadores	No
changes_since	Feed de cambios incrementales: creados/actualizados/retirados/eliminados desde un cursor	Sí, plan Growth o superior

Una herramienta de servicio de filas llamada sin clave nunca toca la base de datos — devuelve un rechazo estructurado que indica la página de clave gratuita, nunca un 401 simple. Cualquier texto de descripción de empleo o empresa devuelto por cualquier herramienta es texto de terceros extraído de un sitio de empleador externo: la descripción de cada herramienta indica al modelo que lo trate como datos, nunca como una instrucción a seguir.

Autenticación

Exactamente una puerta: un encabezado HTTP Authorization: Bearer <key> en la conexión MCP — nunca un parámetro de consulta ?key=, nunca un argumento de herramienta. Una clave gratuita Explore (1,000 registros/mes, sin tarjeta) es suficiente para probar cada herramienta con clave: https://jobopportunitiesapi.org/login?ref=mcp

Cada llamada de herramienta se mide de forma idéntica al endpoint REST que envuelve — mismo plan, misma asignación mensual, mismo límite de tasa. changes_since requiere el plan Growth o superior, igual que /v1/changes.

Configuración del cliente

Claude Desktop / Claude.ai (conector personalizado)

Configuración → Conectores → Agregar conector personalizado, o pega en claude_desktop_config.json:

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

Cursor

.cursor/mcp.json de proyecto o global:

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

Windsurf

Cascade → Plugins → MCP Servers → agrega un servidor personalizado con la URL y el encabezado anteriores, o edita ~/.codeium/windsurf/mcp_config.json directamente (misma forma JSON que la de Cursor).

VS Code

Paleta de comandos → "MCP: Add Server" → HTTP, o agrega a .vscode/mcp.json usando la misma forma JSON que se muestra para Cursor arriba.

Cline

MCP Servers → Configure MCP Servers, misma forma JSON que la de Cursor arriba (Cline lee el bloque mcpServers idéntico).

ChatGPT (modo desarrollador / Apps)

El directorio unificado de plugins de OpenAI requiere un envío ZIP con una cuenta de desarrollador verificada por identidad y un desafío de propiedad de dominio — aún no enviado. Hasta entonces, cualquier cliente de modo desarrollador de ChatGPT compatible con MCP que acepte una URL HTTP Streamable sin procesar con un encabezado estático puede usar la configuración mostrada arriba.

JSON-RPC sin procesar (curl)

Protocolo de enlace:

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"}}}'

Una llamada de herramienta:

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"]}}}'

Metadatos del registro

mcp/server.json es la entrada publicada en el Registro MCP oficial bajo el espacio de nombres verificado por DNS org.jobopportunitiesapi/mcp.

Acerca de JOA

Job Opportunities API — ofertas de empleo en vivo publicadas directamente por empleadores tomadas de los propios sitios de carrera y sistemas de seguimiento de candidatos, con ofertas cerradas conservadas con fechas de cierre. Cada campo está etiquetado como publicado/inferido/ausente (procedencia); las brechas de cobertura se publican, no se ocultan (cifras en vivo: https://jobopportunitiesapi.org/facts). API REST, estadísticas sin clave, páginas web de empleos/empresas, exportación CSV, especificación OpenAPI.

• Sitio web: https://jobopportunitiesapi.org
• Documentación: https://jobopportunitiesapi.org/docs
• Precios: https://jobopportunitiesapi.org/pricing
• Contacto: support@jobopportunitiesapi.org

Licencia

El contenido de este repositorio (documentación, fragmentos de configuración y server.json) está licenciado bajo la Licencia MIT. Este repositorio no contiene código fuente de la API de JOA ni de la implementación del servidor MCP — esos viven en el monorepo privado de JOA y se distribuyen como parte del binario de la API de producción.