Los errores de MCP se dividen en grupos de transporte, autenticación, ámbito/plan, cuota y llamadas de herramientas. Localice el código correspondiente antes de cambiar el código del cliente.
¿Qué debe hacer si el servicio no está disponible?
Una respuesta 503 indica un problema de disponibilidad. Confirme la URL pública, pause las llamadas y reintente más tarde con espera progresiva y acotada. Si persiste, contacte con soporte indicando la hora y el ID de solicitud sin datos sensibles.
¿Por qué fallan las comprobaciones de host u origen?
- Use exactamente
https://app.dureach.com/mcpcon un cliente MCP compatible con streamable HTTP. - Complete el consentimiento OAuth para el espacio de trabajo previsto; guarde las credenciales en el almacén protegido del cliente o en un gestor de secretos del servidor.
- Si se rechaza el host o el origen, verifique la URL configurada y contacte con soporte. No elimine ni falsifique cabeceras de seguridad para eludir el rechazo.
- Conserve el
request_idde la respuesta para diagnóstico; nunca incluya tokens ni filas de resultados en registros compartidos.
¿Por qué falla la autenticación?
| Síntoma | Significado | Solución |
|---|---|---|
401, sin detalle request_id | Token ausente, caducado, revocado o con audiencia incorrecta. | Complete de nuevo el consentimiento OAuth; confirme que la audiencia es el recurso /mcp (/.well-known/oauth-protected-resource/mcp); envíe Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. |
Clave de API REST aceptada en otro lugar, rechazada en /mcp | Las claves de API no son válidas para MCP. | Utilice un token de portador OAuth. Las claves de API siguen siendo válidas solo para sus rutas REST documentadas. |
workspace_context_required (403) | X-Workspace-ID no coincide con el espacio de trabajo del token. | Envíe el ID del espacio de trabajo del token u omita el encabezado. Los tokens nunca cruzan espacios de trabajo. |
¿Por qué falta una herramienta o se rechaza?
| Síntoma | Significado | Solución |
|---|---|---|
Herramienta ausente en tools/list | No disponible para esta conexión. | Revise los permisos concedidos y el acceso del espacio de trabajo con un administrador. |
Unknown tool (INVALID_PARAMS) | El nombre carece del prefijo dureach. o no es una de las 14 herramientas. | Envíe el nombre completo (por ejemplo, dureach.trade.search). El alias companies.list se resuelve como companies.search; otros nombres se rechazan. |
scope_required | El token carece del ámbito de la herramienta. | Revise y conceda solo el permiso necesario para la herramienta. No amplíe el acceso solo para eliminar un error. |
plan_capability_required (403) | El espacio de trabajo carece de la capacidad de plataforma de agentes. | Pida a un administrador que habilite la capacidad o cambie de plan. |
invalid_arguments | Valor fuera de rango, consulta corta, campo desconocido o SQL sobredimensionado. | Compare con la tabla de herramientas; las consultas necesitan 3 o más caracteres, las páginas y límites deben mantenerse en rango, el SQL debe mantenerse dentro de 16 KiB y la gramática de solo lectura. |
company_not_found | ID de companies.read desconocido. | Confirme que el UUID provino de companies.search en el mismo espacio de trabajo. |
policy_not_found / policy_not_authorized | El envío R3 nombra una política desconocida, revocada, caducada o no coincidente. | Pase el policy_id de una política ACTIVE revisada por el propietario y vinculada a este cliente OAuth, ejecute primero dry_run: true y reintente con la misma clave de idempotencia. |
policy_budget_exceeded / policy_daily_cap_exceeded | Límites de envío de la política alcanzados. | Espere a la siguiente ventana diaria o pida a un propietario que revise los límites; no divida envíos entre políticas nuevas para eludir límites. |
recipient_suppressed / recipient_already_attempted | El destinatario se dio de baja, rebotó, no es un lead activo o ya se intentó bajo esta política. | Elimine al destinatario y revise el estado de supresión; nunca reintente el mismo destinatario bajo una política nueva. |
result_too_large | Resultado transmitido superior a 1 MiB. | Reduzca columnas/filtros o baje limit. |
quota_exceeded (429) | Un presupuesto por minuto, hora o día está agotado. | Respete Retry-After; los detalles incluyen limit_type, reset_at, retry_after. Consulte Aprobaciones, políticas y cuotas de MCP. |
| Cuerpo rechazado o truncado | Solicitud mayor de 256.000 bytes. | Acorte el SQL o los argumentos; divida la llamada. |
¿Qué debe enviar a soporte?
Incluya el request_id (o x-request-id), la marca temporal, el nombre de la herramienta, page/limit o la forma del SQL (sin identificadores de clientes cuando sea posible), el estado HTTP y el código de error. Nunca incluya el token de portador, filas completas de contactos ni cargas de webhook.