Para configurar o NVIDIA Auto Ontology MCP no Cursor ou no Claude Desktop, primeiro prepare uma implantação do Auto Ontology com banco de dados ativo e camada semântica compilada; depois, conecte o cliente ao endpoint /mcp. O Cursor usa uma URL HTTP direta, enquanto o Claude Desktop chama mcp-remote pelo npx.

Deixe a camada semântica e o banco prontos antes de ajustar o cliente: conectar ao endpoint, por si só, não prepara os dados para responder a consultas.

O que preparar antes de conectar o cliente

O Auto Ontology MCP é um servidor somente leitura que se comunica com a API pública do Auto Ontology. Ele não guarda as credenciais do banco: as consultas dependem da implantação, de uma camada semântica compilada — que relaciona conceitos de negócio à estrutura dos dados — e de uma conexão ativa com o banco. A documentação do NVIDIA Auto Ontology MCP descreve essa dependência.

O início rápido da NVIDIA usa Docker com Compose v2, uv, uma chave de API da NVIDIA e o banco de exemplo Wide World Importers, da Microsoft. O README oficial do Auto Ontology traz os arquivos e a sequência de configuração.

Antes de iniciar os serviços, configure o ambiente a partir do .env.example. Entre as variáveis indicadas estão DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD e PGADMIN_PASSWORD. O exemplo também traz chaves por função de modelo: elas podem ser substituídas ou removidas para usar DEFAULT_MODELS_API_KEY como alternativa. Troque as senhas padrão; o Compose publica o PostgreSQL, o pgAdmin e o aplicativo web no host.

Prepare a implantação e inicie o MCP

Siga esta ordem para que a conexão do cliente encontre uma implantação pronta:

  1. Configure as variáveis de ambiente. Defina a chave de API, o segredo de autenticação, a URL do aplicativo, a conexão com o banco e as senhas administrativas. Isso prepara os serviços e as contas usadas na implantação.
  2. Inicie o PostgreSQL e carregue o banco de exemplo. A sequência da NVIDIA usa o script de seed do auto-ontology-eval para carregar o Wide World Importers.
  3. Inicie os outros serviços do Compose. Com o banco e os dados de exemplo preparados, suba o restante da implantação.
  4. Ative a compilação semântica. Entre no aplicativo web com a conta de administrador, abra Settings → Semantic Compilation e aguarde a indicação “Semantic compilation is ready”. Uma consulta precisa dessa compilação e de uma conexão ativa com o banco.
  5. Inicie o pacote MCP apontado para o aplicativo web. A configuração de exemplo usa AUTO_ONTOLOGY_API_URL=http://localhost:3000 e executa o pacote com uvx, a partir do subdiretório mcp do repositório da NVIDIA. O endpoint para o cliente fica em http://localhost:3003/mcp.

Configure o Cursor ou o Claude Desktop

Os dois clientes usam o mesmo endpoint, mas recebem a configuração de maneiras diferentes:

ClienteArquivo ou entradaConfiguração do endpoint
Cursor~/.cursor/mcp.json, em mcpServers.auto-ontologyDefina url como http://localhost:3003/mcp.
Claude Desktopclaude_desktop_config.jsonDefina command como npx e use mcp-remote e http://localhost:3003/mcp em args.

Depois de editar o arquivo, reinicie o cliente e conclua o login quando solicitado. A autenticação acontece pelo Auto Ontology; o cliente gerencia o token, e as chamadas usam as permissões da pessoa conectada. Não coloque credenciais do banco no arquivo MCP.

Diagnostique falhas de login e consulta

Se o cliente não encontrar o fluxo de login, confira se a implantação responde no caminho /.well-known/oauth-authorization-server. A documentação da NVIDIA indica uma resposta HTTP 200 para o fluxo descrito; uma imagem pré-compilada mais antiga pode não ter essa rota.

Um erro de URL do recurso protegido pode ocorrer quando os endereços usados não coincidem, por exemplo, localhost em um ponto e 127.0.0.1 em outro. Faça AUTO_ONTOLOGY_MCP_PUBLIC_URL corresponder ao endereço que o cliente realmente usa.

Para uma pergunta sem resultado útil, verifique a implantação antes de ajustar a formulação da consulta:

  1. Execute check_readiness para identificar se falta a compilação semântica ou uma conexão ativa com o banco.
  2. Se a implantação estiver pronta, use check_answerable para verificar se a pergunta pode ser respondida com os conceitos disponíveis.
  3. Se os termos não forem reconhecidos, use search_terms para procurar a nomenclatura registrada.
  4. Quando essas verificações estiverem em ordem, use ask_question. A ferramenta retorna resposta, SQL e linhas, com limite de 100 linhas; row_count e truncated indicam a contagem e se houve truncamento.

Um catálogo preenchido não garante que o banco ainda esteja conectado: os metadados podem continuar visíveis depois que a conexão original foi encerrada. E um erro 403 de um perfil viewer ao consultar conexões pode refletir a permissão administrativa exigida para essa operação, não uma falha geral da implantação.

Mantenha os serviços internos na rede privada

A NVIDIA orienta manter as portas 3001, do backend, e 3002, da ingestão e compilação semântica, em uma rede privada. O backend confia na identidade encaminhada pelo frontend, e as operações de ingestão não têm autenticação própria. As ferramentas MCP documentadas são somente leitura, e cada chamada respeita as permissões da pessoa autenticada.