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

Problema

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

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

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>

Certifique-se de que a solicitação de autenticação use o ponto final do token:
```
/adb/auth/v1/databases/<database-ocid>/token
```
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

Emitir

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

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

Verifique o nome de usuário e a senha do banco de dados usados na solicitação.
Confirme se a conta de usuário do banco de dados está ativa.

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

Emitir

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

Navegue até seu diretório home.
Localize o diretório .mcp_auth.

Exemplos de locais:

Linux / macOS
```
~/.mcp_auth
```
Janelas
```
C:\Users\<username>\.mcp_auth
```
Exclua o diretório .mcp_auth para limpar a sessão de autenticação em cache.
Reinicie o cliente MCP e autentique-se novamente.

As Ferramentas MCP Não Aparecem no Cliente MCP

Problema

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

Confirme se existem ferramentas no banco de dados.
Verifique se as ferramentas foram criadas com sucesso. Consulte Criar Ferramentas Selecionar Agente do AI para obter mais detalhes.
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.
Reinicie ou reconecte o cliente MCP para que ele atualize a lista de ferramentas.

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

Problema

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

Gerar um novo token de portador.
Verifique se o usuário do esquema criou as ferramentas.

Confirme se as ferramentas existem.

SELECT tool_name FROM user_cloud_ai_tools;

Reinicie o cliente e tente novamente.

Erro HTTP Transmitível – 401

Problema

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

Gere um novo token ao portador usando o ponto final OAuth.
Substitua o valor do cabeçalho de Autorização pelo novo token.
```
"Authorization": "Bearer <new-access-token>"
```
Salve o arquivo de configuração do MCP.
Reinicie o cliente.
Reconecte-se ao Servidor MCP.
Reemitir o prompt.

Resultados vazios inesperados

Emitir

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

Verifique se a tabela contém dados.
Verifique as condições de filtro usadas na consulta.
Confirme se o esquema e a tabela corretos são referenciados.

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

Emitir

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

Confirme se o banco de dados usa um Ponto Final Privado.
Recupere o prefixo de nome de host do ponto final privado na console do Autonomous AI Database.
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>
```
Certifique-se de que o cliente MCP seja executado na VCN ou na rede conectada.

Erro ao obter falha

Problema

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

Verifique se o ponto final usa https, não http.
Confirme se o domínio usa oraclecloudapps.com, não oraclecloud.com.
Verifique o identificador da região e o OCID do banco de dados.
Tente a conexão novamente após atualizar a configuração.

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

Emitir

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

Possível Causa

O token do portador expirou durante a sessão.

Resolução

Gerar um novo token de portador.
Atualize o arquivo da configuração.
Reinicie o cliente.
Reconecte-se ao Servidor MCP.

Claude Solução de Problemas

Claude Não Solicita Credenciais do Banco de Dados

Problema

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

Abra o Claude Desktop.
Clique em Menu, selecione Ajuda e clique em Solução de problemas.
Escolha Clear Cache and Restart.
Reinicie Claude e tente a conexão novamente.
Se o problema persistir, exclua a pasta .mcp_auth do seu diretório de usuário.
Limpe os cookies do navegador para dataaccess.adb.<region>.oraclecloudapps.com.
Reinicie Claude novamente e tente novamente.

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

Problema

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

Verifique se o valor da tag de formato livre está definido corretamente.
```
{"name":"mcp_server","enable":true}
```

Confirme se o ponto final usa:

https://dataaccess.adb.<region>.oraclecloudapps.com

Reinicie Claude depois de validar a configuração.

Claude Desktop Mostra o Servidor MCP como Desativado

Problema

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

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;
/
            
```
Reinicie o Claude Desktop após adicionar ou modificar as ferramentas do MCP.
Reconecte o servidor MCP no Claude Desktop.

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

Problema

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

Confirme se você fez log-in como o mesmo usuário de esquema que criou as ferramentas.
Verifique se as ferramentas existem no banco de dados.
```
SELECT tool_name FROM user_cloud_ai_tools;
```
Reinicie o Claude Desktop após a verificação.

Claude se conecta, mas se comporta inesperadamente

Problema

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

Iniciar uma nova sessão de bate-papo.
Reinicie o Claude Desktop.
Reconecte-se ao Servidor MCP.
Verifique as permissões da ferramenta em Conectores.

Solução de Problemas de Cline

Nenhuma caixa de bate-papo visível no Cline

Problema

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

Clique em Done no painel de configuração do MCP.
Retorne à interface de chat do Cline.
Insira o prompt novamente na caixa de bate-papo.

Falha inesperada na solicitação de metadados

Problema

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

Reconecte-se ao Servidor MCP.
Limpe o histórico de prompts ou inicie uma nova sessão de bate-papo.
Reemitir o prompt de metadados.
Se a mesma tabela existir em vários esquemas, qualifique-a com o nome do esquema.
```
Show the metadata details of SALES_USER.CUSTOMERS
```

Verifique os nomes de tabela duplicados no banco de dados.

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

Tópico principal: Servidor MCP do Autonomous AI Database

Documentação do Oracle Cloud Infrastructure

Diagnosticando e Solucionando Problemas do Servidor MCP