Documentação do Oracle Cloud Infrastructure

Diagnosticando e Solucionando Problemas do Servidor MCP

Esta seção descreve problemas comuns que podem ocorrer durante a conexão ou o uso do Servidor MCP do Autonomous AI Database e fornece etapas para diagnosticá-los e resolvê-los.

Problemas Comuns

O Servidor MCP retorna HTTP 404 ao conectar

Emissão

Falha de um cliente MCP ao estabelecer conexão com o Servidor MCP do Autonomous AI Database e retorna o seguinte erro: HTTP 404 Not Found

Possível Causa

Possíveis causas:

  • A configuração do cliente usa o ponto final de autenticação em vez do ponto final MCP.

  • O Servidor MCP não está ativado para o banco de dados.

  • O URL do ponto final contém um OCID ou identificador de região do banco de dados incorreto.

  • O cliente tenta acessar um caminho MCP que não existe.

Resolução

  1. Verifique se o Servidor MCP está ativado para o banco de dados.

  2. Confirme se a configuração do cliente MCP usa o formato de ponto final correto:

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

  3. Certifique-se de que a solicitação de autenticação use o ponto final do token:

    /adb/auth/v1/databases/<database-ocid>/token

  4. Verifique se o identificador de região e o OCID do banco de dados correspondem ao Autonomous AI Database de destino.

Informações adicionais

O ponto final MCP e o ponto final de autenticação usam caminhos diferentes.

O ponto final de autenticação emite tokens OAuth, enquanto o ponto final do MCP processa a ferramenta e as solicitações do agente.

Verifique se o Servidor MCP está ativado para o banco de dados. Consulte Ativar Servidor MCP para saber como ativar o Servidor MCP.

Falha na Autenticação do Cliente MCP ao Solicitar Token

Emissão

Um cliente MCP falha ao obter um token ao portador e retorna um erro de autenticação ao chamar o ponto final do token.

Possível Causa

Possíveis causas:

  • O nome de usuário ou a senha do banco de dados está incorreta.

  • A solicitação de token usa um ponto final incorreto.

  • A conta do usuário do banco de dados está bloqueada ou expirou.

  • As restrições de acesso à rede bloqueiam a solicitação.

Resolução

  1. Confirme se a solicitação de token usa o ponto final de autenticação.

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

  2. Verifique o nome de usuário e a senha do banco de dados usados na solicitação.

  3. Confirme se a conta de usuário do banco de dados está ativa.

  4. Repita a solicitação com um token válido.

    Exemplo de solicitação:

    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>"}'

Informações adicionais

O serviço de autenticação emite um token de portador que os clientes MCP incluem no cabeçalho Authorization ao chamar ferramentas MCP.

Erro de Cliente Inválido Aparece no Browser Durante a Autenticação

Emissão

A página de autenticação exibe a seguinte mensagem ao acessar o servidor MCP:

Invalid Client

Possível Causa

Possíveis causas:

  • Dados de autenticação armazenados em cache pelo cliente MCP.

  • Uma sessão de autenticação desatualizada criada durante uma tentativa de log-in anterior.

Resolução

  1. Navegue até seu diretório home.

  2. Localize o diretório .mcp_auth.

    Exemplos de locais:

    Linux / macOS

    ~/.mcp_auth

    Janelas

    C:\Users\<username>\.mcp_auth

  3. Exclua o diretório .mcp_auth para limpar a sessão de autenticação em cache.

  4. Reinicie o cliente MCP e autentique-se novamente.

As Ferramentas MCP Não Aparecem no Cliente MCP

Emissão

Um cliente MCP se conecta com sucesso ao Servidor MCP, mas não exibe nenhuma ferramenta.

Possível Causa

Possíveis causas:

  • Nenhuma ferramenta personalizada foi criada.

  • O usuário cliente não tem privilégios suficientes para acessar as ferramentas.

  • Falha na criação da ferramenta MCP durante a criação.

  • O status da ferramenta está desativado.

Resolução

  1. Confirme se existem ferramentas no banco de dados.

  2. Verifique se as ferramentas foram criadas com sucesso. Consulte Criar Ferramentas Selecionar Agente do AI para obter mais detalhes.

  3. Certifique-se de que o usuário do banco de dados que se conecta por meio do MCP tenha os privilégios necessários para acessar a ferramenta.

  4. Reinicie ou reconecte o cliente MCP para que ele atualize a lista de ferramentas.

Falha na chamada da ferramenta após aprovação

Emissão

A chamada da ferramenta falha mesmo após o usuário aprová-la.

Possível Causa

O token do portador expirou ou o usuário do esquema não corresponde ao proprietário da ferramenta.

Resolução

  1. Gerar um novo token de portador.

  2. Verifique se o usuário do esquema criou as ferramentas.

  3. Confirme se as ferramentas existem.

    SELECT tool_name FROM user_ai_agent_tools;

  4. Reinicie o cliente e tente novamente.

Erro HTTP Transmitível - 401

Emissão

O cliente mostra a mensagem Streamable HTTP error: O servidor retornou 401 após a autenticação bem-sucedida.

Possível Causa

O token ao portador expirou ou não é mais válido. Os tokens do portador são válidos por aproximadamente uma hora.

Resolução

  1. Gere um novo token ao portador usando o ponto final OAuth.

  2. Substitua o valor do cabeçalho de Autorização pelo novo token. 
    "Authorization": "Bearer <new-access-token>"

  3. Salve o arquivo de configuração do MCP.

  4. Reinicie o cliente.

  5. Reconecte-se ao Servidor MCP.

  6. Reemitir o prompt.

Resultados vazios inesperados

Emissão

A chamada da ferramenta é bem-sucedida, mas não retorna linhas.

Possível Causa

A tabela não contém linhas correspondentes ou as condições de filtro são muito restritivas.

Resolução

  1. Verifique se a tabela contém dados.

  2. Verifique as condições de filtro usadas na consulta.

  3. Confirme se o esquema e a tabela corretos são referenciados.

  4. Teste a consulta na Planilha SQL.

    SELECT COUNT(*) FROM <table_name>;

Falha na Conexão do Servidor MCP Quando o Banco de Dados Usa um Ponto Final Privado

Emissão

Um cliente MCP não pode estabelecer conexão com o Servidor MCP para um banco de dados configurado com um Ponto Final Privado.

Possível Causa

Possíveis causas:

  • O cliente tenta estabelecer conexão de fora da VCN configurada.

  • O URL do ponto final do MCP usa o nome do host público em vez do nome do host do ponto final privado.

  • As regras de segurança de rede bloqueiam a solicitação.

Resolução

  1. Confirme se o banco de dados usa um Ponto Final Privado.

  2. Recupere o prefixo de nome de host do ponto final privado na console do Autonomous AI Database.

  3. Atualize o URL do ponto final do MCP. Consulte Acesso a Ponto Final Privado para obter mais detalhes.

    Exemplo de formato:

    https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>

  4. Certifique-se de que o cliente MCP seja executado na VCN ou na rede conectada.

Problema ao Estabelecer Conexão com o Ponto Final do MCP que Usa um Banco de Dados de Ponto Final Privado por meio do Pareamento da VCN

Emissão

Não é possível estabelecer conexão com o ponto final do MCP para uma instância do Autonomous AI Database Serverless ativada para ponto final privado após configurar o pareamento de VCN.

Possível Causa

A resolução de DNS ou a conectividade de rede entre a VCN do aplicativo e a VCN do ponto final privado do Autonomous AI Database não está configurada corretamente.

Resolução

Se você já tiver configurado o pareamento de VCN entre a VCN do aplicativo e a VCN do ponto final privado do Autonomous AI Database, verifique a resolução de DNS e a conectividade de rede na VM do aplicativo.

  1. Verifique a resolução de DNS.

    Executar:

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

    O nome do host deve ser resolvido para o endereço IP do ponto final privado do Autonomous AI Database. Neste exemplo, mypepdb é o hostname_prefix para o banco de dados ativado por ponto final privado. Se isso não acontecer, configure o resolvedor de DNS apropriado para a VCN do aplicativo para que o nome do host seja resolvido para o endereço IP do ponto final privado.

  2. Verifique a conectividade com a porta 443.

    Executar:

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

    A conexão deve ter sucesso. Se o comando expirar, verifique se as tabelas de roteamento, as listas de segurança e as regras de NSG (grupo de segurança de rede) para ambas as VCNs permitem tráfego HTTPS (porta TCP 443) na conexão de pareamento de VCN.

  3. Verifique a conectividade HTTPS com o ponto final do MCP.

    Executar:

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

    Verifique a saída detalhada para confirmar se o nome do host é resolvido para o endereço IP do ponto final privado do Autonomous AI Database e se a VM do aplicativo estabelece uma conexão HTTPS com o ponto final do MCP na porta 443.

Erro ao obter falha

Emissão

O cliente mostra um erro de falha na extração ao estabelecer conexão com o Servidor MCP.

Possível Causa

O URL MCP está incorreto, o HTTP é usado em vez de HTTPS, o identificador da região está errado.

Resolução

  1. Verifique se o ponto final usa https, não http.

  2. Confirme se o domínio usa oraclecloudapps.com, não oraclecloud.com.

  3. Verifique o identificador da região e o OCID do banco de dados.

  4. Tente a conexão novamente após atualizar a configuração.

Eliminações de Conexão Durante a Sessão

Emissão

O cliente para de trabalhar durante uma sessão ativa.

Possível Causa

O token do portador expirou durante a sessão.

Resolução

  1. Gerar um novo token de portador.

  2. Atualize o arquivo da configuração.

  3. Reinicie o cliente.

  4. Reconecte-se ao Servidor MCP.

Claude Solução de Problemas

Claude Não Solicita Credenciais do Banco de Dados

Emissão

O Claude Desktop não exibe um prompt de log-in para credenciais do banco de dados após a reinicialização.

Possível Causa

Os dados de autenticação armazenados em cache estão interferindo.

Resolução

  1. Abra o Claude Desktop.

  2. Clique em Menu, selecione Ajuda e clique em Solução de problemas.

  3. Escolha Clear Cache and Restart.

  4. Reinicie Claude e tente a conexão novamente.

  5. Se o problema persistir, exclua a pasta .mcp_auth do seu diretório de usuário.

  6. Limpe os cookies do navegador para dataaccess.adb.<region>.oraclecloudapps.com.

  7. Reinicie Claude novamente e tente novamente.

O Servidor MCP Não É Exibido como Em Execução

Emissão

O Claude Desktop não mostra o Servidor MCP em um estado Em Execução.

Possível Causa

O recurso MCP está desativado, o ponto final está incorreto ou a configuração do cliente está incompleta.

Resolução

  1. Verifique se o valor da tag de formato livre está definido corretamente. 
    {"name":"mcp_server","enable":true}
  2. Confirme se o ponto final usa: 
    https://dataaccess.adb.<region>.oraclecloudapps.com
  3. Reinicie Claude depois de validar a configuração.

Claude Desktop Mostra o Servidor MCP como Desativado

Emissão

Depois de adicionar uma configuração de servidor MCP no Claude Desktop, o servidor MCP aparece desativado e as ferramentas não estão disponíveis.

Possível Causa

Possíveis causas:

  • Nenhuma ferramenta Selecionar Agente do AI foi criada para o usuário do banco de dados.

  • O Claude Desktop foi iniciado antes da criação das ferramentas MCP.

  • O cliente MCP armazenou em cache uma configuração de ferramenta anterior.

Resolução

  1. Confirme se existem ferramentas Selecionar Agente AI para o usuário do banco de dados. Consulte USER_AI_AGENT_TOOLS View para obter uma lista das ferramentas do usuário do banco de dados.

    Exemplo:

    BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/

  2. Reinicie o Claude Desktop após adicionar ou modificar as ferramentas do MCP.

  3. Reconecte o servidor MCP no Claude Desktop.

Claude Desktop Retorna HTTP 502 Durante a Autenticação do Servidor MCP

Emissão

O Claude Desktop falha ao estabelecer conexão com o Servidor MCP do Autonomous AI Database e retorna um erro semelhante ao seguinte:

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

A resposta também pode conter conteúdo HTML semelhante ao seguinte:

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

A resposta também pode conter conteúdo HTML semelhante ao seguinte:

Possível Causa

Esse problema pode ocorrer pelos seguintes motivos:

  • A configuração do Claude Desktop inclui uma definição transport não suportada ao usar mcp-remote.

  • O argumento --allow-http obrigatório não foi encontrado na seção args.

  • O cliente MCP recebe uma resposta do gateway HTML em vez da resposta JSON OAuth esperada por causa da configuração incorreta do cliente.

  • O URL do ponto final do MCP está incorreto ou incompleto.

  • A configuração de rede ou proxy bloqueia a solicitação OAuth.

Ao usar o mcp-remote, o utilitário gerencia a configuração de transporte internamente. Especificar manualmente o transporte pode causar falhas na negociação do protocolo.

Resolução

Remova a seguinte linha da configuração do Claude Desktop ao usar mcp-remote:

"transport": "streamable-http"

Adicione o argumento --allow-http necessário na seção de argumentos.

Por exemplo:

"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 também o seguinte:

  • O Servidor MCP está ativado para o banco de dados.

  • O URL do ponto final usa o identificador de região e o OCID do banco de dados corretos.

  • O Node.js está instalado e acessível a partir do caminho configurado.

  • O Claude Desktop é reiniciado após a atualização da configuração.

Consulte Configurar Servidor MCP no AI Agent Application para obter mais informações.

As ferramentas não aparecem após o login no Claude

Emissão

Claude se conecta com sucesso, mas as ferramentas esperadas não aparecem.

Possível Causa

Você efetuou log-in como um usuário de esquema diferente, as ferramentas foram criadas em outro esquema ou Claude precisa ser reiniciado após a criação da ferramenta.

Resolução

  1. Confirme se você fez log-in como o mesmo usuário de esquema que criou as ferramentas.

  2. Verifique se as ferramentas existem no banco de dados.

    SELECT tool_name FROM user_cloud_ai_tools;

  3. Reinicie o Claude Desktop após a verificação.

Claude se conecta, mas se comporta inesperadamente

Emissão

Claude carrega e conecta, mas as respostas não correspondem ao comportamento esperado.

Possível Causa

A sessão de chat atual contém contexto desatualizado, a sessão precisa ser atualizada ou as permissões da ferramenta não estão configuradas conforme esperado.

Resolução

  1. Iniciar uma nova sessão de bate-papo.

  2. Reinicie o Claude Desktop.

  3. Reconecte-se ao Servidor MCP.

  4. Verifique as permissões da ferramenta em Conectores.

Solução de Problemas de Cline

Nenhuma caixa de bate-papo visível no Cline

Emissão

A caixa de entrada Cline chat não fica visível após a visualização da configuração e das ferramentas do servidor MCP.

Possível Causa

O usuário ainda está no painel de configuração do MCP.

Resolução

  1. Clique em Done no painel de configuração do MCP.

  2. Retorne à interface de chat do Cline.

  3. Insira o prompt novamente na caixa de bate-papo.

Falha inesperada na solicitação de metadados

Emissão

A solicitação de metadados falha ou retorna um resultado inesperado quando o usuário solicita metadados de tabela.

Possível Causa

A conexão da sessão se tornou obsoleta, o histórico de prompts afetou a seleção da ferramenta ou a mesma tabela existe em vários esquemas.

Resolução

  1. Reconecte-se ao Servidor MCP.

  2. Limpe o histórico de prompts ou inicie uma nova sessão de bate-papo.

  3. Reemitir o prompt de metadados.

  4. Se a mesma tabela existir em vários esquemas, qualifique-a com o nome do esquema.

    Show the metadata details of SALES_USER.CUSTOMERS

  5. Verifique os nomes de tabela duplicados no banco de dados.

     SELECT owner, table_name
  FROM all_tables
  WHERE table_name = 'CUSTOMERS';