Solución de problemas de MCP

Diagnostica problemas de detección de herramientas, autenticación, acceso a la organización, argumentos y resultados inciertos antes de volver a intentarlo.

Elige qué revisar según el síntoma: si falta una herramienta, revisa la conexión; si se rechaza una llamada, revisa el error de argumentos o permisos. Conserva el nombre de la herramienta, los datos de entrada que no sean secretos, la respuesta y el recurso o la revisión de origen correspondientes. Esa evidencia ayuda a retomar el trabajo previsto sin repetir una operación de escritura cuyo resultado se desconoce.

Faltan las herramientas esperadas #

Compara el punto de conexión configurado con el inventario que devuelve el cliente. /mcp y /main exponen las mismas herramientas autenticadas; /account redirige a /main después de la autenticación.

Busca members_listMemberships y engines_list y sigue los ejemplos de lectura inicial. Usa la respuesta actual de tools/list para obtener los nombres y esquemas exactos. Que exista un punto de conexión de la API no significa que MCP lo exponga.

Si solo algunas herramientas están ocultas, revisa la lista de herramientas permitidas y las aprobaciones del cliente, y habilita solo lo que necesita la tarea. Si una herramienta debería estar disponible pero no aparece, conserva los datos del servidor y su versión, junto con la salida de detección que no contenga secretos, para incluirlos en un reporte.

GET devuelve 405 #

Configura Streamable HTTP en /mcp. Después de la autenticación, una solicitud GET a /mcp o /main devuelve 405 con Allow: POST; el cliente envía mensajes MCP mediante POST. Si el token falta o no es válido, se devuelve 401 antes de despachar la solicitud. En cambio, una solicitud autenticada a /account devuelve 308 con destino a /main. Estas respuestas GET no permiten comprobar si funciona una conexión MCP POST válida. Revisa el error de conexión del cliente después de seleccionar el transporte correcto.

La autenticación o la organización es incorrecta #

Para 401, comprueba que la conexión haya completado OAuth con la cuenta de usuario de Lingo.dev que quieres usar. El servidor alojado requiere un token de portador de usuario válido; no acepta claves de API personales ni de servicio en x-api-key ni como valor del token de portador. Deja que el cliente renueve su autorización o vuelve a conectarte desde la administración de cuentas del cliente. No incluyas tokens en los diagnósticos.

Llama a members_listMemberships, elige la organización que quieres usar en data y pasa su ID en el campo de organización de la siguiente herramienta. Para engines_list, ese campo es orgId. Elegir otra organización de la misma lista no requiere una nueva autorización OAuth. Vuelve a conectarte si la persona que inició sesión no es la correcta; un simple reinicio puede reutilizar la sesión guardada.

Si la membresía aparece en ssoRequired, inicia sesión en Lingo.dev a través del proveedor de identidad de esa organización y vuelve a conectarte. Si tanto data como ssoRequired están vacíos, completa la configuración de la organización en https://lingo.dev/orgs/start y luego vuelve a consultar las membresías. Una organización no disponible puede no existir, no estar entre las membresías del usuario o requerir SSO; no interpretes todas esas respuestas como una credencial vencida.

Si una herramienta rechaza una operación por falta de un permiso o derecho, revisa los requisitos de la operación en lugar de autenticarte una y otra vez. El acceso a la organización y el permiso para realizar una operación de escritura específica se comprueban por separado. Explica qué autorización falta sin elegir un rol o una credencial con más privilegios sin avisar.

Una herramienta indica que la configuración de la organización está incompleta #

La organización se creó recientemente y quien la creó aún no ha terminado de configurarla en la aplicación web: las integraciones, los integrantes del equipo y el primer motor. Las herramientas a nivel de organización pueden quedar bloqueadas hasta que se complete la configuración; volver a intentarlo o autorizar de nuevo no completa esos pasos. members_listMemberships sigue disponible. Abre el enlace del mensaje, https://lingo.dev/orgs/<orgId>, con la cuenta de quien creó la organización, completa los pasos que indica el mensaje y luego repite la llamada. Consulta Terminar de configurar una nueva organización.

La herramienta rechaza los argumentos #

Compara los datos de entrada con el esquema exacto que devuelve la conexión. Los argumentos actuales de las herramientas son campos planos y conservan los valores anidados donde lo indica el esquema. No agregues contenedores inventados como body, params o query. Proporciona explícitamente el campo de organización cuando sea obligatorio; no se agrega automáticamente a partir del token de portador. El campo opcional intent describe la tarea. Consulta Capacidades para conocer las operaciones de cuenta compatibles.

Comprueba qué identifica cada ID. members_remove.id es el ID de membresía de members_list; members_setRole.userId identifica al usuario de esa membresía. Un ID de motor de localización no puede sustituir a un ID de registro de solicitudes. Copia exactamente los cursores opacos o los pares de marca de tiempo e ID con toda su precisión, en lugar de reconstruirlos a partir de las fechas mostradas.

Respeta las distinciones del esquema entre valores omitidos y nulos, números y cadenas, arreglos y valores individuales. Revisa el esquema de la herramienta conectada antes de aplicar una solución alternativa a un error de argumentos.

El resultado de una operación de escritura en la cuenta o de un trabajo es incierto #

Consulta el recurso correspondiente o el estado del trabajo antes de volver a intentarlo. Puede ocurrir un error de red después de que el servidor haya aceptado la creación de una clave, una invitación, una decisión de revisión, una sugerencia o un trabajo. Comprueba si el cambio previsto ya existe en lugar de enviarlo de nuevo automáticamente.

Si enviaste un trabajo de aprovisionamiento, consulta provisioningJobs_get con el ID de trabajo guardado antes de decidir si vuelves a intentarlo. Para otras operaciones, revisa el recurso guardado y el contrato de finalización de la herramienta conectada. Consulta la referencia de la CLI o de la API para los flujos de trabajo de traducción.

Falta documentación o evidencia #

Busca con localization_search y luego pasa el path de un resultado a docs_fetch para leer la página completa. Si la ruta falla, vuelve a buscar la tarea y usa un resultado actualizado. La base de conocimientos usa una ruta de almacenamiento distinta de la del sitio web basado en archivos, por lo que una página del sitio puede faltar o estar desactualizada en ese índice. Consulta la referencia actual del sitio web antes de concluir que la funcionalidad no está disponible.

Al reportar una limitación de MCP que siga sin resolverse, incluye la tarea que intentaste realizar, el nombre exacto de la herramienta, la versión del servidor y la respuesta sin datos secretos. La confirmación de recepción de un reporte no garantiza una fecha de solución.

Para una consulta sobre calidad, identifica qué falta: evidencia de origen, una evaluación completada, un criterio aplicable o una respuesta concluyente. Cada caso requiere pasos distintos. Medir explica cómo reportar la evidencia disponible sin dar por aprobados los casos sin respuesta.