Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Solucione problemas do servidor MCP local

Use as informações desta página para ajudar a solucionar problemas com o Local MCP.

Se você tiver problemas com o Local MCP, examine os logs do servidor para obter informações que possam ajudar a solucionar o problema.

Por padrão, o Local MCP grava os logs em disco e também os envia para o cliente MCP. Você pode alterar a opção loggers para especificar para onde os logs são enviados. Para obter detalhes sobre as opções do Local MCP, consulte Opções de configuração do servidor MongoDB MCP.

A tabela a seguir mostra os diretórios padrão onde o Local MCP armazena os arquivo de log:

Sistema operacional
Diretório de registro padrão

Windows

%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs

macOS e Linux

~/.mongodb/mongodb-mcp/.app-logs

Para alterar o caminho do registro, defina um destes:

  • logPath opção em um arquivo de configuração JSON ou na linha de comando ao iniciar o Local MCP

  • MDB_MCP_LOG_PATH Variável de ambiente

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 Cadeias de conexão.

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.0 para 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 .

O Local MCP fornece três categorias principais de FERRAMENTAS:

  • FERRAMENTAS do Atlas para gerenciar a infraestrutura do Atlas

  • FERRAMENTAS locais do Atlas para gerenciar implantações locais, semelhantes ao que a Atlas CLI oferece

  • FERRAMENTAS de banco de dados para operações de dados

A tabela a seguir compara a configuração de cada ferramenta.

Aspecto de configuração
Ferramentas do Atlas
Ferramentas locais do Atlas
Ferramentas de banco de dados

Requisitos de autenticação

Obrigatório: credenciais da Atlas API
• apiClientId (ID da conta de serviço)
• apiClientSecret (Segredo da conta de serviço)

Obrigatório: tempo de execução do Docker
• Nenhuma credencial adicional é necessária
• Gerencia automaticamente implantações locais

Opcional: Vários métodos de conexão
• String de conexão pré-configurada
• Credenciais do Atlas para atlas-connect-cluster
• Conexão em tempo de execução por meio da ferramenta connect
• Implantação local por meio de atlas-local-connect-deployment

Método de conexão

Conexão baseada em API para a Atlas Gerenciamento API
• Nenhuma conexão direta com o banco de dados necessária
• Usa pontos de extremidade da Atlas REST API

Gerenciamento de implantação local
• Usa contêineres Docker
• Não é necessário acesso à rede externa

Conexão direta ao banco de dados MongoDB. Várias opções disponíveis:
• String de conexão configurada
• Prompt de conexão em tempo de execução
• Descoberta de cluster do Atlas
• Conexão de implantação local

Requisitos de permissão

Funções da conta de serviço (nível de projeto do Atlas):
• Project Read Only (mínimo para operações de leitura)
• Project Owner (para criação/gerenciamento de cluster)
• Organization Owner (para criação de projeto)

Requisitos do sistema:
• Permissões de tempo de execução do Docker
• Acesso ao sistema de arquivos local
• Funcionalidade de gerenciamento de contêineres

Funções de usuários de banco de dados (quando aplicável):
• readAnyDatabase (modo somente leitura)
• readWriteAnyDatabase (operações completas)
• Função personalizada para bancos de dados/coleção específicos

Opções de configuração

Variáveis de ambiente:
MDB_MCP_API_CLIENT_ID ou
MDB_MCP_API_CLIENT_SECRET

Linha de comando:
• --apiClientId
• --apiClientSecret

Variáveis de ambiente:
• DOCKER_HOST (opcional)

Linha de comando:
• Nenhuma configuração MCP específica necessária
• Detecta automaticamente o tempo de execução do Docker

Variáveis de ambiente (opcional):
MDB_MCP_CONNECTION_STRING

Linha de comando (opcional):
• string de conexão como argumento posicional:
--connectionString

Métodos de tempo de execução:
• Conexão interativa via prompts LLM
• Descoberta do Atlas baseada em credenciais

Impacto do modo somente leitura

• operações de leitura: ✅ Disponível
• inspeção de cluster: ✅ Disponível
• criação de cluster: ❌ Desativado
• gerenciamento de usuários: ❌ Desativado

• Criação de implantação local: ✅ Disponível
• Inspeção de implantação: ✅ Disponível
• Gerenciamento de contêineres: ✅ Disponível
• Sem restrições somente leitura

• Operações de leitura: ✅ Disponível
• Operações de query: ✅ Disponível
• Agregações: ✅ Disponível, desde que não tenham um estágio $out ou $merge.
• Inserir/Atualizar/Excluir: ❌ Desativado
• Criação de índice: ❌ Desativado

Categorias de ferramentas

Pode ser desativado com:
--disabledTools atlas ou
MDB_MCP_DISABLED_TOOLS="atlas"

Pode ser desativado com:
--disabledTools atlas ou
MDB_MCP_DISABLED_TOOLS="atlas"

Pode ser desativado com:
--disabledTools mongodb ou
MDB_MCP_DISABLED_TOOLS="mongodb"

Requisitos de rede

HTTPS de saída para a API do Atlas:
• Conexão padrão à Internet

Rede Docker local:
• Acesso ao daemon do Docker
• Disponibilidade de porta local
• Sem requisitos de rede externa

Conexão ao cluster MongoDB (quando aplicável):
• Atlas: mongodb+srv:// (porta 27017)
• Cluster sharded (porta 27016)
• Autogerenciado: host/porta personalizados
• Implantações locais: rede Docker
• Acesso à VPC/rede conforme necessário

Operações disponíveis

• Gerenciamento da organização
• Gerenciamento de projetos
• Ciclo de vida do cluster (criar, inspecionar, excluir)
• Gerenciamento de usuários de banco de dados
• Configuração da lista de acesso
• Recomendações do Performance Advisor
• Gerenciamento de alertas

• Criação e gerenciamento de implantação local
• Operações de ciclo de vida do contêiner
• Configuração de cluster local
• Configuração do ambiente de desenvolvimento
• Gerenciamento de implantação de teste

• Operações CRUD (localizar, inserir, atualizar, excluir)
• Pipeline de agregação
• Gerenciamento de índice
• Administração de coleção e banco de dados
• Inspeção de esquema
• Operações de pesquisa vetorial
• Operações de pesquisa lexical
• Exportação de dados

Error Scenarios

Credenciais de API ausentes:
As ferramentas do Atlas retornam: "Credenciais de API do Atlas não configuradas"

Permissões insuficientes:
Erros HTTP 403 da API do Atlas

Docker Indisponível:
"O daemon do Docker não está em execução" ou "O Docker não está instalado"

Problemas no contêiner:
Conflitos de porta, restrições de recurso

Falhas de conexão (quando configurado):
Tempos limite de rede, falhas de autenticação

Permissões de banco de dados ausentes:
Erros de autorização do MongoDB

Credenciais temporárias

Não aplicável:
Usa credenciais de conta de serviço persistentes

Não aplicável:
As implantações locais usam autenticação gerenciada por contêiner

Usuários de banco de dados gerados automaticamente (quando aplicável):
Ao usar credenciais da API do Atlas sem string de conexão:
• Nome de usuário/senha aleatórios
• Expiração de 4horas por padrão
• Atribuição automática de função

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:

  • String de conexão pré-configurada: configure o connectionString via CLI, variável de ambiente ou arquivo de configuração para acesso persistente ao banco de dados.

  • Atlas Cluster Connect: utilize a ferramenta atlas-connect-cluster com credenciais Atlas API para descobrir e conectar automaticamente a Atlas clusters.

  • Conexão de tempo de execução: use a ferramenta connect para fornecer connection strings interativamente durante conversas LLM - nenhuma pré-configuração necessária.

  • Conexão de implantação local: use o atlas-local-connect-deployment 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 implantações 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.