Resolución de problemas de MCP

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

El síntoma te indica qué comprobar a continuación: si falta una herramienta, revisa la conexión; si se rechaza una llamada, comprueba el error de argumentos o permisos. Conserva el nombre de la herramienta, los datos de entrada que no sean secretos, la respuesta y la revisión pertinente del recurso o de la fuente. Esta información 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 tras la autenticación.

Busca members_listMemberships y engines_list y sigue los ejemplos de lectura inicial. Consulta 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 se ocultan algunas herramientas, revisa la lista de herramientas permitidas y las aprobaciones del cliente, y habilita únicamente lo necesario para la tarea. Si una herramienta debería estar disponible pero no aparece, conserva los datos del servidor y su versión, junto con los resultados de detección que no contengan secretos, para incluirlos en un informe.

GET devuelve 405 #

Configura Streamable HTTP en /mcp. Tras la autenticación, una solicitud GET a /mcp o /main devuelve 405 con Allow: POST; el cliente envía los mensajes de 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 hacia /main. Estas respuestas GET no permiten comprobar si funciona una conexión POST válida de MCP. Revisa el error de conexión del cliente después de seleccionar el transporte correcto.

La autenticación o la organización no es la correcta #

Para 401, comprueba que la conexión haya completado OAuth con el usuario de Lingo.dev que querías utilizar. El servidor alojado exige un token de portador de usuario válido; no se acepta una clave de API personal 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 su gestión de cuentas. No incluyas tokens en los datos de diagnóstico.

Llama a members_listMemberships, elige la organización que corresponda 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 ha iniciado sesión no es la correcta; reiniciar sin más puede reutilizar la sesión guardada.

Si la pertenencia a la organización 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 vuelve a consultar las pertenencias a organizaciones. Una organización no disponible puede no existir, no estar entre aquellas a las que pertenece el usuario o exigir SSO; no interpretes todas estas respuestas como indicios de una credencial caducada.

Si una herramienta deniega una operación por falta de permisos o de derechos de uso, 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 concreta se comprueban por separado. Explica qué autorización falta sin elegir, sin avisar, un rol o una credencial con más privilegios.

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

La organización se ha creado recientemente y la persona que la creó aún no ha terminado de configurarla en la aplicación web: las integraciones, los miembros del equipo y el primer motor. Las herramientas de ámbito organizativo pueden quedar bloqueadas hasta que se complete la configuración; volver a intentarlo o renovar la autorización no completa esos pasos. members_listMemberships sigue disponible. Abre el enlace del mensaje, https://lingo.dev/orgs/<orgId>, con la cuenta de la persona que creó la organización, completa los pasos que indica el mensaje y 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, con valores anidados allí donde los define el esquema. No añadas estructuras contenedoras inventadas de body, params o query. Incluye explícitamente el campo de organización cuando sea obligatorio; no se incorpora automáticamente a partir del token de portador. El campo opcional intent describe la tarea. Consulta Capacidades para ver las operaciones de cuenta admitidas.

Comprueba qué identifica cada ID. members_remove.id es el ID de pertenencia a la organización que devuelve members_list; members_setRole.userId identifica al usuario asociado a esa pertenencia. Un ID de motor de localización no puede sustituir a un ID del 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 que se muestran.

Respeta las distinciones del esquema entre valores omitidos y nulos, números y cadenas, matrices y valores individuales. Comprueba 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 pertinente o el estado del trabajo antes de volver a intentarlo. Puede producirse 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 has enviado un trabajo de aprovisionamiento, consulta provisioningJobs_get con el ID de trabajo guardado antes de decidir si debes volver a intentarlo. Para otras operaciones, revisa el recurso guardado y las condiciones 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 faltan pruebas #

Busca con localization_search y 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 utiliza un resultado actualizado. La base de conocimientos utiliza una ruta de almacenamiento distinta de la del sitio web basado en archivos, por lo que una página del sitio web puede no aparecer en ese índice o estar desactualizada. Consulta la documentación de referencia actual del sitio web antes de concluir que la capacidad no está disponible.

Al informar de una carencia de MCP aún sin resolver, incluye la tarea que has intentado realizar, el nombre exacto de la herramienta, la versión del servidor y la respuesta sin datos secretos. El acuse de recibo del informe no garantiza una fecha de resolución.

Si tienes una consulta sobre calidad, identifica qué falta: pruebas de la fuente, una evaluación completada, un criterio aplicable o una respuesta concluyente. Cada caso requiere pasos distintos. Medición explica cómo comunicar las pruebas disponibles sin dar por aprobados los casos sin respuesta.