Use as informações nesta página para solucionar problemas com o servidor MongoDB MCP.
arquivos de log
Se você tiver problemas com o servidor MCP, examine os registros do servidor MCP para obter informações que possam ajudar a solucionar o problema.
Por padrão, o servidor MCP grava os logs no disco e também envia os logs para o cliente MCP. Você pode alterar a opção loggers para especificar para onde os registros são enviados. Para obter detalhes sobre as opções do servidor MCP, consulte Opções de configuração do servidor MongoDB MCP.
A tabela a seguir mostra os diretórios padrão onde o servidor MCP armazena os arquivos de log:
Sistema operacional | Diretório de registro padrão |
|---|---|
Windows |
|
macOS e Linux |
|
Para alterar o caminho do registro, defina um destes:
logPathopção em um arquivo de configuração JSON ou em uma linha de comando ao iniciar o servidor MCPMDB_MCP_LOG_PATHVariável de ambiente
Problemas com a cadeia de conexão
Verifique se o arquivo de configuração está correto e se você está usando uma string de conexão válida para o MongoDB deployment.
Para formatação e exemplos de string de conexão, consulte string de conexão.
Problemas de transporte HTTP
Se você estiver usando o transporte HTTP e tiver problemas de conexão:
Verifique se o URL de conexão do cliente inclui o caminho do endpoint
/mcp:http://<server-address>:3000/mcp Se estiver conectando a um servidor remoto (computador diferente, contêiner ou instância de nuvem), verifique se o servidor foi iniciado com
--httpHost=0.0.0.0para aceitar conexões remotas:npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --readOnly Certifique-se de que a porta especificada esteja aberta e acessível a partir do seu computador cliente .
Guia de Configuração do Atlas Tools versus Database Tools
Visão geral
O Servidor MongoDB MCP oferece três categorias principais de ferramentas: Ferramentas Atlas para gerenciar a infraestrutura do Atlas , Ferramentaslocais do Atlas para gerenciar implementações locais de forma semelhante ao que o Atlas CLI oferece, e Ferramentas de banco de dados para operações de dados. A tabela a seguir compara a configuração de cada ferramenta.
Tabela de comparação de configurações
Aspecto de configuração | Ferramentas do Atlas | Ferramentas locais do Atlas | Ferramentas de banco de dados |
|---|---|---|---|
Requisitos de autenticação | Required: Atlas API credentials • apiClientId (Service Account ID)• apiClientSecret (Service Account Secret) | Required: Docker runtime • No additional credentials needed • Automatically manages local deployments | Optional: Multiple connection methods • Pre-configured connection string • Atlas credentials for atlas-connect-cluster• Runtime connection via connect tool• Local deployment via atlas-local-connect-deployment |
Método de conexão | API-based connection to Atlas Management API • No direct database connection needed • Uses Atlas REST API endpoints | Local deployment management • Uses Docker containers • No external network access required | Direct connection to MongoDB database. Multiple options available: • Configured connection string • Runtime connection prompt • Atlas cluster discovery • Local deployment connection |
Requisitos de permissão | Service Account Roles (Atlas project-level): • Project Read Only (minimum for read operations)• Project Owner (for cluster creation/management)• Organization Owner (for project creation) | System Requirements: • Docker runtime permissions • Local file system access • Container management capabilities | Database User Roles (when applicable): • readAnyDatabase (read-only mode)• readWriteAnyDatabase (full operations)• Custom roles for specific databases/collections |
Opções de configuração | Environment Variables: MDB_MCP_API_CLIENT_ID orMDB_MCP_API_CLIENT_SECRETCommand Line: • --apiClientId• --apiClientSecret | Environment Variables: • DOCKER_HOST (optional)Command Line: • No specific MCP configuration required • Automatically detects Docker runtime | Environment Variables (optional): MDB_MCP_CONNECTION_STRINGCommand Line (optional): • Connection string as positional argument: --connectionStringRuntime Methods: • Interactive connection via LLM prompts • Atlas credential-based discovery |
Impacto do modo somente leitura | • Read operations: ✅ Available • Cluster inspection: ✅ Available • Cluster creation: ❌ Disabled • User management: ❌ Disabled | • Local deployment creation: ✅ Available • Deployment inspection: ✅ Available • Container management: ✅ Available • No read-only restrictions | • Read operations: ✅ Available • Query operations: ✅ Available • Aggregations: ✅ Available as long as they don't have a $out or $merge stage.• Insert/Update/Delete: ❌ Disabled • Index creation: ❌ Disabled |
Categorias de ferramentas | Can be disabled with: --disabledTools atlas orMDB_MCP_DISABLED_TOOLS="atlas" | Can be disabled with: --disabledTools atlas orMDB_MCP_DISABLED_TOOLS="atlas" | Can be disabled with: --disabledTools mongodb orMDB_MCP_DISABLED_TOOLS="mongodb" |
Requisitos de rede | Outbound HTTPS to Atlas API: • Standard internet connection | Local Docker Network: • Docker daemon access • Local port availability • No external network requirements | Connection to MongoDB cluster (when applicable): • Atlas: mongodb+srv:// (port 27017)• Sharded clusters (port 27016) • Self-managed: Custom host/port • Local deployments: Docker network • VPC/network access as required |
Operações disponíveis | • Organization management • Project management • Cluster lifecycle (create, inspect, delete) • Database user management • Access list configuration • Performance Advisor recommendations • Alert management | • Local deployment creation and management • Container lifecycle operations • Local cluster configuration • Development environment setup • Testing deployment management | • CRUD operations (find, insert, update, delete) • Aggregation pipelines • Index management • Collection and database administration • Schema inspection • Vector search operations • Data export |
Cenários de erro | Missing API Credentials: Atlas tools return: "Atlas API credentials not configured" Insufficient Permissions: HTTP 403 errors from Atlas API | Docker Unavailable: "Docker daemon not running" or "Docker not installed" Container Issues: Port conflicts, resource constraints | Connection Failures (when configured): Network timeouts, authentication failures Missing Database Permissions: MongoDB authorization errors |
Credenciais temporárias | Not applicable: Uses persistent service account credentials | Not applicable: Local deployments use container-managed authentication | Auto-generated database users (when applicable): When using Atlas API credentials without connection string: • Random username/password • 4-hour expiration by default • Automatic role assignment |
Métodos de conexão do banco de dados
As ferramentas de banco de dados oferecem suporte a vários métodos de conexão para acomodar diferentes casos de uso e requisitos de segurança:
Connection string pré-configurada: configure
connectionStringo via CLI, variável de ambiente ou arquivo de configuração para acesso persistente ao banco de dados .Atlas Cluster Connect: utilize a
atlas-connect-clusterferramenta com credenciais Atlas API para descobrir e conectar automaticamente a Atlas clusters.Conexão de tempo de execução: use a
connectferramenta para fornecer connection strings interativamente durante conversas LLM - nenhuma pré-configuração necessária.Conexão de implantação local: use
atlas-local-connect-deploymento com Docker para criar e conectar-se a implantações locais do Atlas - requer Docker, mas nenhuma configuração.
Recomendações de segurança:
Bancos de dados de produção: use connection strings pré-configuradas por meio de variáveis de ambiente ou credenciais do Atlas API para conexões seguras e automatizadas.
Desenvolvimento/teste: A conexão de tempo de execução ou sistemas locais fornecem flexibilidade sem configuração persistente.
Segurança de chat: evite métodos de conexão de tempo de execução, a menos que tenha certeza de que o histórico de chat não será armazenado ou compartilhado com terceiros.