Documentación de Oracle Cloud Infrastructure

Resolución de problemas del servidor MCP

En esta sección, se describen los problemas comunes que se pueden producir al conectarse al servidor MCP de la base de datos de IA autónoma o al utilizarlo, y se proporcionan pasos para diagnosticarlos y resolverlos.

Problemas Comunes

El servidor MCP devuelve HTTP 404 al conectarse

Problema

Un cliente MCP no se puede conectar al servidor MCP de la base de datos de IA autónoma y devuelve el siguiente error: HTTP 404 Not Found

Causa Posible

Entre las causas posibles se incluyen:

  • La configuración del cliente utiliza el punto final de autenticación en lugar del punto final de MCP.
  • El servidor MCP no está activado para la base de datos.
  • La URL de punto final contiene un OCID de base de datos o un identificador de región incorrectos.
  • El cliente intenta acceder a una ruta de MCP que no existe.

Resolución

  1. Verifique que el servidor MCP esté activado para la base de datos.
  2. Confirme que la configuración del cliente MCP utiliza el formato de punto final correcto: 
    https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  3. Asegúrese de que la solicitud de autenticación utiliza el punto final de token: 
    /adb/auth/v1/databases/<database-ocid>/token
  4. Verifique que el identificador de región y el OCID de base de datos coinciden con la base de datos de IA autónoma de destino.

Información adicional

El punto final de MCP y el punto final de autenticación utilizan diferentes rutas.

El punto final de autenticación emite tokens OAuth, mientras que el punto final de MCP procesa las solicitudes de agente y la herramienta.

Verifique que el servidor MCP esté activado para la base de datos. Consulte Enable MCP Server para obtener información sobre cómo activar el servidor MCP.

La autenticación del cliente MCP falla al solicitar el token

Problema

Un cliente MCP no puede obtener un token de portador y devuelve un error de autenticación al llamar al punto final del token.

Causa Posible

Entre las causas posibles se incluyen:

  • El nombre de usuario o la contraseña de la base de datos no son correctos.
  • La solicitud de token utiliza un punto final incorrecto.
  • La cuenta de usuario de la base de datos está bloqueada o ha vencido.
  • Las restricciones de acceso a la red bloquean la solicitud.

Resolución

  1. Confirme que la solicitud de token utiliza el punto final de autenticación.

    https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token

  2. Verifique el nombre de usuario y la contraseña de la base de datos utilizados en la solicitud.

  3. Confirme que la cuenta de usuario de la base de datos está activa.

  4. Vuelva a intentar la solicitud con un token válido.

    Ejemplo de solicitud:

    curl --location "https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token" \
--header "Content-Type: application/json" \
--data '{"grant_type":"password","username":"ADMIN","password":"<password>"}'

Información adicional

El servicio de autenticación emite un token de portador que los clientes MCP incluyen en la cabecera Authorization al llamar a las herramientas MCP.

Aparece un error de cliente no válido en el explorador durante la autenticación

Problema

La página de autenticación muestra el siguiente mensaje al conectarse al servidor MCP:

Invalid Client

Causa Posible

Entre las causas posibles se incluyen:

  • Datos de autenticación almacenados en caché por el cliente MCP.
  • Una sesión de autenticación obsoleta creada durante un intento de conexión anterior.

Resolución

  1. Navegue hasta el directorio raíz.

  2. Localice el directorio .mcp_auth.

    Ubicaciones de ejemplo:

    Linux / macOS

    ~/.mcp_auth

    Ventanas

    C:\Users\<username>\.mcp_auth

  3. Suprima el directorio .mcp_auth para borrar la sesión de autenticación almacenada en caché.

  4. Reinicie el cliente MCP y vuelva a autenticarse.

Las herramientas MCP no aparecen en el cliente MCP

Problema

Un cliente MCP se conecta correctamente al servidor MCP, pero no muestra ninguna herramienta.

Causa Posible

Entre las causas posibles se incluyen:

  • No se han creado herramientas personalizadas.
  • El usuario cliente no tiene privilegios suficientes para acceder a las herramientas.
  • La creación de la herramienta MCP ha fallado durante la creación.
  • El estado de la herramienta está desactivado.

Resolución

  1. Confirme que las herramientas existen en la base de datos.

  2. Verifique que las herramientas se hayan creado correctamente. Consulte Crear herramientas de agente de AI de selección para obtener más información.

  3. Asegúrese de que el usuario de la base de datos que se conecta a través de MCP tiene los privilegios necesarios para acceder a la herramienta.
  4. Reinicie o vuelva a conectar el cliente MCP para que refresque la lista de herramientas.

La llamada de herramienta falla después de la aprobación

Problema

La llamada a la herramienta falla incluso después de que el usuario la aprueba.

Causa Posible

El token de portador ha caducado o el usuario del esquema no coincide con el propietario de la herramienta.

Resolución

  1. Genere un nuevo token de portador.
  2. Verifique que el usuario de esquema ha creado las herramientas.

  3. Confirme que las herramientas existen.

    SELECT tool_name FROM user_cloud_ai_tools;
  4. Reinicie el cliente y vuelva a intentarlo.

Error de HTTP Streamable – 401

Problema

El cliente muestra el mensaje Streamable HTTP error: el servidor ha devuelto 401 después de la autenticación correcta.

Causa Posible

El token de portador ha caducado o ya no es válido. Los tokens portadores son válidos durante aproximadamente una hora.

Resolución

  1. Genere un nuevo token de portador mediante el punto final OAuth.

  2. Sustituya el valor de cabecera de autorización por el nuevo token.

    "Authorization": "Bearer <new-access-token>"
  3. Guarde el archivo de configuración de MCP.
  4. Reinicie el cliente.
  5. Vuelva a conectarse al servidor MCP.
  6. Vuelva a emitir el mensaje.

Resultados vacíos inesperados

Problema

La llamada a la herramienta se realiza correctamente, pero no devuelve ninguna fila.

Causa Posible

La tabla no contiene filas coincidentes o las condiciones de filtro son demasiado restrictivas.

Resolución

  1. Verifique que la tabla contiene datos.
  2. Compruebe las condiciones de filtro utilizadas en la consulta.
  3. Confirme que se hace referencia al esquema y la tabla correctos.
  4. Pruebe la consulta en la hoja de trabajo de SQL. 
    SELECT COUNT(*) FROM <table_name>;

La conexión del servidor MCP falla cuando la base de datos utiliza un punto final privado

Problema

Un cliente MCP no puede conectarse al servidor MCP para una base de datos configurada con un punto final privado.

Causa Posible

Entre las causas posibles se incluyen:

  • El cliente intenta conectarse desde fuera de la VCN configurada.
  • La URL de punto final de MCP utiliza el nombre de host público en lugar del nombre de host de punto final privado.
  • Las reglas de seguridad de red bloquean la solicitud.

Resolución

  1. Confirme que la base de datos utiliza un punto final privado.
  2. Recupere el prefijo de nombre de host de punto final privado de la consola de la base de datos de IA autónoma.

  3. Actualice la URL de punto final de MCP. Consulte Acceso de punto final privado para obtener más información.

    Ejemplo de Formato:

    https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  4. Asegúrese de que el cliente MCP se ejecute en la VCN o la red conectada.

Error al recuperar

Problema

El cliente muestra un error de recuperación fallida al conectarse al servidor MCP.

Causa Posible

La URL de MCP es incorrecta, se utiliza HTTP en lugar de HTTPS, el identificador de región es incorrecto.

Resolución

  1. Verifique que el punto final utiliza https, no http.
  2. Confirme que el dominio utiliza oraclecloudapps.com, no oraclecloud.com.
  3. Verifique el identificador de región y el OCID de la base de datos.
  4. Vuelva a intentar la conexión después de actualizar la configuración.

Se borran las conexiones durante la sesión

Problema

El cliente deja de trabajar durante una sesión activa.

Causa Posible

El token de portador ha caducado durante la sesión.

Resolución

  1. Genere un nuevo token de portador.
  2. Actualice el fichero de configuración.
  3. Reinicie el cliente.
  4. Vuelva a conectarse al servidor MCP.

Solución de problemas de Claude

Claude no solicita credenciales de base de datos

Problema

Claude Desktop no muestra una petición de datos de inicio de sesión para las credenciales de la base de datos después del reinicio.

Causa Posible

Los datos de autenticación almacenados en caché están interfiriendo.

Resolución

  1. Abra Claude Desktop.
  2. Haga clic en Menú, seleccione Ayuda y, a continuación, haga clic en Resolución de problemas.
  3. Seleccione Clear Cache and Restart.
  4. Reinicie Claude y vuelva a intentar la conexión.
  5. Si el problema persiste, suprima la carpeta .mcp_auth del directorio de usuario.
  6. Borre las cookies del navegador para dataaccess.adb.<region>.oraclecloudapps.com.
  7. Reinicie Claude de nuevo y vuelva a intentarlo.

El servidor MCP no se muestra como en ejecución

Problema

Claude Desktop no muestra el servidor MCP en estado Running.

Causa Posible

La función MCP está desactivada, el punto final es incorrecto o la configuración del cliente está incompleta.

Resolución

  1. Verifique que el valor de la etiqueta de formato libre esté definido correctamente.

    {"name":"mcp_server","enable":true}
  2. Confirme que el punto final utiliza:
    https://dataaccess.adb.<region>.oraclecloudapps.com
    .
  3. Reinicie Claude después de validar la configuración.

Claude Desktop muestra el servidor MCP como desactivado

Problema

Después de agregar una configuración de servidor MCP en Claude Desktop, el servidor MCP aparece desactivado y las herramientas no están disponibles.

Causa Posible

Entre las causas posibles se incluyen:

  • No se han creado herramientas de Select AI Agent para el usuario de la base de datos.
  • Claude Desktop comenzó antes de crear las herramientas MCP.
  • El cliente MCP almacenó en caché una configuración de herramienta anterior.

Resolución

  1. Confirme que existen herramientas Select AI Agent para el usuario de la base de datos. Consulte USER_AI_AGENT_TOOLS View para obtener una lista de las herramientas para el usuario de la base de datos.

    Ejemplo:

    BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/
  2. Reinicie Claude Desktop después de agregar o modificar las herramientas MCP.
  3. Vuelva a conectar el servidor MCP en Claude Desktop.

Las herramientas no aparecen después de iniciar sesión en Claude

Problema

Claude se conecta correctamente, pero las herramientas esperadas no aparecen.

Causa Posible

Se ha conectado como un usuario de esquema diferente, las herramientas se han creado en otro esquema o Claude se debe reiniciar después de la creación de la herramienta.

Resolución

  1. Confirme que se ha conectado como el mismo usuario de esquema que ha creado las herramientas.

  2. Verifique que las herramientas existen en la base de datos.

    SELECT tool_name FROM user_cloud_ai_tools;
  3. Reinicie Claude Desktop después de la verificación.

Claude se conecta pero se comporta inesperadamente

Problema

Claude carga y se conecta, pero las respuestas no coinciden con el comportamiento esperado.

Causa Posible

La sesión de chat actual contiene un contexto obsoleto, se debe refrescar la sesión o los permisos de herramienta no están configurados como se esperaba.

Resolución

  1. Inicie una nueva sesión de chat.
  2. Reinicie Claude Desktop.
  3. Vuelva a conectarse al servidor MCP.
  4. Verifique los permisos de la herramienta en Conectores.

Solución de problemas de línea

No hay ninguna caja de chat visible en línea

Problema

El cuadro de entrada de chat Cline no está visible después de ver las herramientas y la configuración del servidor MCP.

Causa Posible

El usuario aún está en el panel de configuración de MCP.

Resolución

  1. Haga clic en Done en el panel de configuración de MCP.
  2. Vuelva a la interfaz de chat de Cline.
  3. Vuelva a introducir la petición de datos en el cuadro de chat.

La solicitud de metadatos falla inesperadamente

Problema

La solicitud de metadatos falla o devuelve un resultado inesperado cuando el usuario solicita metadatos de tabla.

Causa Posible

La conexión de sesión se ha quedado obsoleta, el historial de peticiones de datos ha afectado a la selección de la herramienta o la misma tabla existe en varios esquemas.

Resolución

  1. Vuelva a conectarse al servidor MCP.
  2. Borre el historial de peticiones de datos o inicie una nueva sesión de chat.
  3. Vuelva a emitir la petición de datos de metadatos.
  4. Si existe la misma tabla en varios esquemas, califique la tabla con el nombre del esquema. 
    Show the metadata details of SALES_USER.CUSTOMERS
  5. Verifique los nombres de tabla duplicados en la base de datos. 
    SELECT owner, table_name
                FROM all_tables
                WHERE table_name = 'CUSTOMERS';