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:
- 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.
- Inicie o PostgreSQL e carregue o banco de exemplo. A sequência da NVIDIA usa o script de seed do
auto-ontology-evalpara carregar o Wide World Importers. - Inicie os outros serviços do Compose. Com o banco e os dados de exemplo preparados, suba o restante da implantação.
- 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.
- Inicie o pacote MCP apontado para o aplicativo web. A configuração de exemplo usa
AUTO_ONTOLOGY_API_URL=http://localhost:3000e executa o pacote comuvx, a partir do subdiretóriomcpdo repositório da NVIDIA. O endpoint para o cliente fica emhttp://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:
| Cliente | Arquivo ou entrada | Configuração do endpoint |
| Cursor | ~/.cursor/mcp.json, em mcpServers.auto-ontology | Defina url como http://localhost:3003/mcp. |
| Claude Desktop | claude_desktop_config.json | Defina 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:
- Execute
check_readinesspara identificar se falta a compilação semântica ou uma conexão ativa com o banco. - Se a implantação estiver pronta, use
check_answerablepara verificar se a pergunta pode ser respondida com os conceitos disponíveis. - Se os termos não forem reconhecidos, use
search_termspara procurar a nomenclatura registrada. - Quando essas verificações estiverem em ordem, use
ask_question. A ferramenta retorna resposta, SQL e linhas, com limite de 100 linhas;row_countetruncatedindicam 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.