Reclee

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

MCPAPI REST
URLhttps://app.reclee.com/api/mcphttps://app.reclee.com/api/v1
ProtocoloJSON-RPC sobre Streamable HTTP, sin estadoHTTP + JSON
AutenticaciónOAuth 2.1 (el cliente lo resuelve solo) o API key en AuthorizationAPI key en Authorization
Descubrimientotools/list, con el JSON Schema de cada toolOpenAPI 3.1 público
Lecturas35 tools READ, con datos resumidos para el modeloRutas GET con el objeto completo
Escrituras97 toolsLas mismas 97 como POST /actions/<tool>, más otras rutas POST, PATCH y PUT
Paginaciónlimit hasta 50 (20 por defecto) y pagepageSize hasta 200 (50 por defecto) y page
Respuesta de una escriturastructuredContent con data, links, next y costEl mismo objeto, como cuerpo JSON
ErroresisError: true con { error, missing, suggestions }Status HTTP con { error, ... }; un 402 trae además qué límite se agotó
IdempotenciaNo hay: reintentar una escritura puede ejecutarla dos vecesHeader Idempotency-Key
Rate limit60 por minuto por persona, compartidoEl mismo cupo
ConfirmaciónLa pide el cliente, guiado por destructiveHintLa pide tu integración
HistorialLo escrito queda con origen MCPQueda 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.

ToolGET 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.

En esta página