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

Incidencia

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

Incidencia

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

Incidencia

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

Incidencia

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

Incidencia

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_ai_agent_tools;

  4. Reinicie el cliente y vuelva a intentarlo.

Error de HTTP Streamable - 401

Incidencia

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

Incidencia

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

Incidencia

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.

Problemas al conectarse al punto final de MCP que utiliza una base de datos de punto final privada mediante el intercambio de tráfico de VCN

Incidencia

No puede conectarse al punto final de MCP para una instancia sin servidor de base de datos de IA autónoma activada para punto final privado después de configurar el intercambio de tráfico de VCN.

Causa Posible

La resolución de DNS o la conectividad de red entre la VCN de la aplicación y la VCN de punto final privado de la base de datos de IA autónoma no están configuradas correctamente.

Resolución

Si ya ha configurado el intercambio de VCN entre la VCN de la aplicación y la VCN de punto final privado de la base de datos de IA autónoma, verifique la resolución de DNS y la conectividad de red desde la máquina virtual de la aplicación.

  1. Verifique la resolución de DNS.

    Ejecutar:

    nslookup mypepdb.adb.us-ashburn-1-1.oraclecloudapps.com

    El nombre de host debe resolverse en la dirección IP de punto final privado de la base de datos de IA autónoma. En este ejemplo, mypepdb es el valor hostname_prefix para la base de datos activada de punto final privado. Si no lo hace, configure el solucionador de DNS adecuado para la VCN de la aplicación para que el nombre de host se resuelva en la dirección IP de punto final privado.

  2. Verifique la conectividad con el puerto 443.

    Ejecutar:

    nc -vz mypepdb.adb.us-ashburn-1-1.oraclecloudapps.com 443

    La conexión debe ser correcta. Si se agota el tiempo de espera del comando, verifique que las tablas de rutas, las listas de seguridad y las reglas del grupo de seguridad de red (NSG) de ambas redes virtuales en la nube permitan el tráfico HTTPS (puerto TCP 443) en la conexión de intercambio de VCN.

  3. Verifique la conectividad HTTPS al punto final de MCP.

    Ejecutar:

    bash\ncurl -v https://mypepdb.adb.us-ashburn-1-1.oraclecloudapps.com/adb/mcp\n

    Revise la salida detallada para confirmar que el nombre de host se resuelve en la dirección IP de punto final privado de Autonomous AI Database y que la máquina virtual de la aplicación establece una conexión HTTPS al punto final de MCP en el puerto 443.

Error al recuperar

Incidencia

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

Incidencia

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

Incidencia

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

Incidencia

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

Incidencia

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 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.

Claude Desktop devuelve HTTP 502 durante la autenticación del servidor MCP

Incidencia

Claude Desktop no se puede conectar al servidor MCP de la base de datos de IA autónoma y devuelve un error similar al siguiente:

[27860] Fatal error: ServerError: HTTP 502: Invalid OAuth error response:
                SyntaxError: Unexpected token '<'

La respuesta también puede contener contenido HTML similar al siguiente:

<html>
	<head><title>502 Bad Gateway</title></head>
	<body>
	<center><h1>502 Bad Gateway</h1></center>
	</body>
</html>

La respuesta también puede contener contenido HTML similar al siguiente:

Causa Posible

Este problema se puede producir por los siguientes motivos:

  • La configuración de Claude Desktop incluye un valor transport no soportado al utilizar mcp-remote.

  • Falta el argumento --allow-http necesario en la sección args.

  • El cliente MCP recibe una respuesta de gateway HTML en lugar de la respuesta JSON de OAuth esperada debido a una configuración de cliente incorrecta.

  • La URL de punto final de MCP es incorrecta o está incompleta.

  • La configuración de red o proxy bloquea la solicitud de OAuth.

Al utilizar mcp-remote, la utilidad gestiona la configuración de transporte internamente. La especificación manual del transporte puede provocar fallos en la negociación del protocolo.

Resolución

Elimine la siguiente línea de la configuración de Claude Desktop al utilizar mcp-remote:

"transport": "streamable-http"

Agregue el argumento --allow-http necesario en la sección de argumentos.

Por ejemplo:

"mcpServers": {
"adb-mcp-server": {
"command": "C:\\Program Files\\nodejs\\npx.cmd",
"args": [
"-y",
"mcp-remote",
"--allow-http",
"https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>"
]
}
}

Verifique también lo siguiente:

  • El servidor MCP está activado para la base de datos.

  • La URL de punto final utiliza el identificador de región y el OCID de base de datos correctos.

  • Node.js está instalado y se puede acceder a él desde la ruta de acceso configurada.

  • Claude Desktop se reinicia después de actualizar la configuración.

Consulte Configuración del servidor MCP en la aplicación de agente AI para obtener más información.

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

Incidencia

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

Incidencia

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

Incidencia

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

Incidencia

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';