*MCP › Guías*

# Solución de problemas

> La mayoría de problemas son la URL, los permisos o un cliente que conserva una lista antigua de herramientas.

## El cliente dice que no está autorizado

Una llamada sin credencial recibe un HTTP 401 con un cuerpo de problema y una cabecera `WWW-Authenticate` que apunta a los metadatos de OAuth. Un cliente con OAuth inicia el inicio de sesión; uno con clave necesita la cabecera. Con una clave, el código dice por qué: [`api_key_invalid`](https://docs.filmo.io/es/rest-api/errors/api_key_invalid), [`api_key_revoked`](https://docs.filmo.io/es/rest-api/errors/api_key_revoked), [`api_key_expired`](https://docs.filmo.io/es/rest-api/errors/api_key_expired), [`api_key_owner_inactive`](https://docs.filmo.io/es/rest-api/errors/api_key_owner_inactive) o [`api_key_owner_not_admin`](https://docs.filmo.io/es/rest-api/errors/api_key_owner_not_admin).

## La URL no es la correcta

La única URL es `https://app.filmo.io/api/v1/mcp`. Otro host de producción responde con una redirección (308) y, para un cliente que no la sigue en un POST, con un error JSON-RPC que nombra esta URL. Un cliente que sigue la redirección pierde la cabecera `Authorization` cuando cambia el origen, así que el inicio de sesión falla de un modo que parece una clave incorrecta. Escribe la URL exactamente como se muestra.

## Falta una herramienta

- Con una clave, el catálogo lista solo lo que la clave puede llamar: comprueba sus permisos con el scope de la herramienta en su página. También omite las herramientas cuyo add-on no tiene la cuenta (una cuenta en prueba las tiene todas).
- Con OAuth, no se garantiza que un cliente vuelva a listar las herramientas después de que des tu consentimiento. Empieza una conversación nueva después de conectar.
- Una herramienta que necesita un add-on que la cuenta no tiene no aparece en la lista; llamarla de todos modos devuelve [`addon_required`](https://docs.filmo.io/es/rest-api/errors/addon_required). Consulta [Planes y add-ons](https://docs.filmo.io/es/concepts/plans-and-add-ons).
- Puede que el cliente supere su límite de herramientas y descarte algunas. Usa un preset: consulta [Límites y contexto](https://docs.filmo.io/es/mcp/guides/limits-and-context).

## Un permiso (scope) no está marcado o una llamada dice insufficient scope

Las escrituras, `workflows:run` y `ai:ask` empiezan sin marcar en la pantalla de consentimiento, aunque el cliente los haya pedido. Márcalos a mano si el asistente los necesita. Para cambiar los permisos después de conectar, quita el conector y vuelve a añadirlo.

## No he iniciado este consentimiento

No lo apruebes. Lee [Antes de aprobar](https://docs.filmo.io/es/mcp/authentication#before-you-approve).

## Una llamada tarda demasiado o agota el tiempo

[`filmo_ai_ask`](https://docs.filmo.io/es/mcp/tools/ai/filmo-ai-ask) puede tardar decenas de segundos. Sube el timeout del cliente o haz una pregunta más concreta. Las listas con muchas filas tardan más en devolverse y en leerse: pide `limit` 20.

## Demasiadas peticiones

[`rate_limited`](https://docs.filmo.io/es/rest-api/errors/rate_limited): espera `retryAfter` segundos. Las herramientas de disponibilidad comparten una cuota aparte de 30 llamadas por minuto.

## OAuth no funciona en un servidor ni en un contenedor

Los clientes que abren un navegador para iniciar sesión (Claude Code, Codex, Gemini CLI) lo necesitan. En una máquina sin navegador, usa una clave de API guardada en el entorno.

## Una clave filtrada

Revócala en la página API y MCP de los ajustes de la aplicación y crea otra con los mismos permisos (scope). Una clave revocada deja de funcionar al instante. Después, comprueba qué hizo. [Seguridad](https://docs.filmo.io/es/further-reading/security#leaked-key) tiene el procedimiento completo.

## Pedir ayuda

Indica el `requestId` del problema, la herramienta y la hora. No envíes nunca la clave.

---

URL canónica: https://docs.filmo.io/es/mcp/guides/troubleshooting  
Última actualización: 2026-10-25