MCP o REST
Cuándo conviene el servidor MCP y cuándo la API REST, en qué se diferencian y cómo se corresponde cada tool con su ruta.
El servidor MCP y la API REST operan sobre el mismo sistema, con la misma credencial y las mismas reglas. La diferencia es para quién está pensado cada uno: el MCP, para un modelo de lenguaje que decide qué hacer; la API REST, para código que ya sabe qué hacer.
Cuándo usar cada uno
Usa el MCP cuando quien decide es un agente de IA: un asistente que conversa con un reclutador, un agente que trabaja una vacante de punta a punta, o Claude conectado a Reclee. Las tools traen descripciones escritas para el modelo, respuestas resumidas, next con lo que sigue, y annotations que le dicen al cliente qué confirmar.
Usa la API REST cuando escribes una integración determinística: sincronizar el CRM con otro sistema, importar candidatos desde un formulario, un reporte nocturno. Tienes respuestas completas, más rutas, paginación más grande, códigos HTTP e idempotencia.
Puedes usar los dos a la vez: la misma API key sirve para ambos.
Comparación
| MCP | API REST | |
|---|---|---|
| URL | https://app.reclee.com/api/mcp | https://app.reclee.com/api/v1 |
| Protocolo | JSON-RPC sobre Streamable HTTP, sin estado | HTTP + JSON |
| Autenticación | OAuth 2.1 (el cliente lo resuelve solo) o API key en Authorization | API key en Authorization |
| Descubrimiento | tools/list, con el JSON Schema de cada tool | OpenAPI 3.1 público |
| Lecturas | 35 tools READ, con datos resumidos para el modelo | Rutas GET con el objeto completo |
| Escrituras | 97 tools | Las mismas 97 como POST /actions/<tool>, más otras rutas POST, PATCH y PUT |
| Paginación | limit hasta 50 (20 por defecto) y page | pageSize hasta 200 (50 por defecto) y page |
| Respuesta de una escritura | structuredContent con data, links, next y cost | El mismo objeto, como cuerpo JSON |
| Errores | isError: true con { error, missing, suggestions } | Status HTTP con { error, ... }; un 402 trae además qué límite se agotó |
| Idempotencia | No hay: reintentar una escritura puede ejecutarla dos veces | Header Idempotency-Key |
| Rate limit | 60 por minuto por persona, compartido | El mismo cupo |
| Confirmación | La pide el cliente, guiado por destructiveHint | La pide tu integración |
| Historial | Lo escrito queda con origen MCP | Queda con origen API |
Reintentos sin idempotencia
Por MCP no hay Idempotency-Key. Si una llamada de escritura se corta (timeout, red) y no sabes si llegó, lee el estado antes de repetirla. Para escrituras que no pueden duplicarse, en particular las que gastan créditos, la API REST con Idempotency-Key es más segura.
Escrituras: tool ↔ acción
Cada tool que escribe es una acción REST con el mismo nombre, el mismo cuerpo y la misma respuesta:
tools/call { "name": "close_job_post", "arguments": { … } }
POST /api/v1/actions/close_job_post { … }curl -s https://app.reclee.com/api/mcp \
-H "Authorization: Bearer $RECLEE_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "close_job_post",
"arguments": {
"jobPostId": "9b2e4f10-6c3d-4a8e-b5f1-0d7a2c9e8f34",
"closeReason": "El cliente cubrió el puesto internamente."
}
}
}'Las dos devuelven { "data": { "status": "CLOSED" }, "links": [ … ] }: por MCP dentro de structuredContent, por REST como cuerpo. El detalle de cada acción está en Acciones.
Una tool READ no existe como acción: POST /api/v1/actions/get_job_post contesta 405. Se lee con su GET.
Lecturas: tool ↔ GET
Cada lectura del MCP tiene una ruta GET que lee lo mismo, pero no siempre con la misma forma: varias tools combinan en una respuesta lo que por REST son dos o tres rutas, y recortan campos que al modelo no le sirven. Esta tabla da la ruta más cercana (relativa a /api/v1); la forma exacta de cada una está en la Referencia.
| Tool | GET más cercano |
|---|---|
list_job_posts | /job-posts |
get_job_post | /job-posts/{jobPostId} |
get_job_post_metrics | /job-posts/{jobPostId}/metrics |
list_job_post_team | /job-posts/{jobPostId}/members |
list_applications | /job-posts/{jobPostId}/applications |
get_application | /ats/applications/{applicationId}/context |
list_application_comments | /ats/applications/{applicationId}/comments |
list_screening_answers | /ats/applications/{applicationId}/screening |
list_labels | /ats/labels |
list_interviews | /ats/applications/{applicationId}/interviews |
list_interview_types | /ats/interview-types |
list_interview_questions | /ats/interviews/{interviewId}/questions |
list_profiles | /talent/pool |
get_profile | /talent/pool/{profileId}/profile |
list_tags | /talent/tags |
list_merge_candidates | /talent/pool/identity-reviews |
get_cv_import | /talent/pool/cvs/jobs/{jobId} |
get_talent_search | /talent/searches/{searchId} |
list_bookmarks | /talent/bookmarks |
list_longlists | /sourcing/longlists |
get_longlist | /sourcing/longlists/{longlistId}/detail |
get_talent_icp | /sourcing/talent-icps/{talentIcpId} |
list_sourcing_searches | /sourcing/search-definitions/with-performance |
list_match_scores | /job-posts/{jobPostId}/match-scores |
list_leads | /crm/leads |
get_lead | /crm/leads/{leadId} |
list_contacts | /crm/leads/{leadId}/contacts |
list_lead_activity | /crm/leads/{leadId}/activity |
list_crm_stages | /crm/stages |
list_requests | /crm/requests |
get_request | /crm/requests/{requestId} |
list_placements | /crm/requests/{requestId}/placements |
list_members | /account/members |
get_usage | /billing/usage-standing |
list_help_articles | /help/articles |
Lo que solo está en REST
La API REST tiene rutas que no tienen tool, porque son configuración o administración y no trabajo de reclutamiento: la cuenta y el workspace, los miembros e invitaciones, la facturación, el sitio de empleo, las notificaciones, las importaciones masivas del CRM y la exportación de datos. Ver la Referencia.