> ## Documentation Index > Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt > Use this file to discover all available pages before exploring further. # Conectar o Devin ao MongoDB > Conecte o Devin ao MongoDB Atlas com um usuário de banco de dados de escopo restrito, uma conta de serviço do Atlas, o mongosh e o Atlas CLI em um blueprint ou o servidor MCP do MongoDB. O Devin pode trabalhar com seus dados do MongoDB como faria um engenheiro com uma connection string somente leitura: ver o que as coleções realmente contêm, descobrir por que uma consulta está lenta, testar uma migração em um banco de dados sandbox e abrir um PR. Este guia faz essa configuração com identidades que você cria para o Devin, de modo que ele nunca atue em nome de um dos seus engenheiros. Tudo fica na sua conta do Atlas: um usuário de banco de dados, uma conta de serviço, ferramentas do MongoDB instaladas por meio de um [blueprint de ambiente](/pt-BR/onboard-devin/environment/blueprints) e, opcionalmente, um servidor MCP. Comece com acesso restrito (somente leitura em produção) e amplie as funções depois: são as funções que definem os limites, e você as altera no Atlas sem precisar mexer no Devin.

Dois planos, duas identidades

| Plano | O que ele acessa | Identidade do Devin | Credencial | | - | - | - | - | | **Plano de dados** | Bancos de dados, documentos, índices, `explain()` | Um **usuário de banco de dados** | Nome de usuário e senha em uma connection string | | **Plano de controle** | Clusters, índices do Search, Performance Advisor, logs de consultas lentas, usuários de banco de dados, listas de acesso | Uma **service account do Atlas** | Client ID e client secret do OAuth 2.0 | Um usuário de banco de dados não consegue chamar a Atlas Administration API, e uma service account não consegue ler documentos pela API. A maioria das equipes começa apenas com o plano de dados e adiciona a service account quando o Devin precisa do Performance Advisor ou dos logs de consultas lentas (clusters dedicados, M10 ou superior). Duas ressalvas: * Uma service account com permissão para criar usuários de banco de dados (`GROUP_OWNER`, `GROUP_DATABASE_ACCESS_ADMIN`) pode criar para si mesma uma identidade no plano de dados. O servidor MCP do MongoDB faz exatamente isso quando recebe uma solicitação para se conectar a um cluster (Opção B). * Os dados de consultas lentas incluem os valores literais das consultas.

Escolha como o Devin se conecta

Os três caminhos usam o mesmo acesso à rede (Etapa 1) e as mesmas identidades (Etapa 2); o que muda é o que o Devin pode manter consigo. | Caminho | Ideal para | Configuração | | - | - | - | | [**Opção A: CLI em um blueprint**](#option-a-cli-in-a-blueprint) | Tarefas que o Devin executa e repete em um repositório: migrações, backfills, dados de seed, testes com dados de formato real | Quatro Devin Secrets e um blueprint curto. Comece por aqui. | | [**Opção B: servidor MCP do MongoDB**](#option-b-mongodb-mcp-server) | Descoberta de schema e análise de consultas/índices como ferramentas, com as proteções `--readOnly` e `--indexCheck` | Um servidor MCP STDIO personalizado com as mesmas credenciais. Complementa a Opção A. | | [**Opção C: plugin do MongoDB Atlas**](#option-c-mongodb-atlas-plugin) | Perguntas sobre o Atlas e leituras em todo o projeto, sem armazenar uma credencial do MongoDB na sessão | Plugin do Marketplace, login via OAuth como um usuário dedicado do Atlas; modo de acesso da organização definido como **Read**. |

Por que conectar o Devin ao MongoDB?

* **O schema está nos próprios documentos.** O MongoDB não tem `information_schema`, e os modelos do Mongoose ou do Prisma acabam divergindo do que está realmente armazenado. O Devin coleta amostras das coleções em produção e trabalha com base na estrutura real. * **O ciclo de consultas lentas se resolve em uma única sessão.** O Devin lê o Performance Advisor e o log de consultas lentas, executa `explain()` na coleção real, encontra o código que dispara a consulta e abre um PR com a correção e o índice proposto. * **As funções do usuário do banco de dados definem o que o Devin pode acessar.** Comece com acesso somente leitura em produção e um sandbox `devin_dev` para gravações; cada ação fica registrada nos logs do Atlas com a identidade própria do Devin.

Pré-requisitos

**Atlas** * Um projeto com um cluster. * `Organization Owner` para criar uma conta de serviço; `Project Owner` para o usuário do banco de dados e as listas de acesso. **Devin** * Permissão para editar o [blueprint do ambiente](/pt-BR/onboard-devin/environment/blueprints) e adicionar [Segredos](/pt-BR/product-guides/secrets). * Para as opções via MCP, a permissão **Manage MCP Servers**. **Rede** * Os IPs do Devin incluídos na lista de acesso por IP do projeto (Etapa 1). * Se você usa uma [network policy](/pt-BR/product-guides/security-profiles) do Devin, permita `*.mongodb.net` e `cloud.mongodb.com`, além dos hosts de onde o blueprint faz as instalações: `pgp.mongodb.com` e `repo.mongodb.org` (Opção A), `registry.npmjs.org` e `nodejs.org` (Opção B). O driver se conecta pela porta 27017, e não pela 443; como as entradas da policy são hostnames ou CIDRs, não há porta para configurar. Os builds do snapshot são executados sob a mesma policy.

Etapa 1: Libere o acesso à rede

O Atlas recusa conexões de IPs que não estão na lista de acesso por IP do projeto. Adicione os IPs listados em [Lista de permissões de IP](/pt-BR/admin/common-issues#ip-allowlisting), em vez de digitá-los de memória. Tenants dedicados têm sua própria saída de rede; confirme com a equipe responsável pela sua conta. ```bash theme={null} atlas accessLists create --type ipAddress --comment "Devin" --projectId atlas accessLists create --type cidrBlock --comment "Devin" --projectId ``` A lista contém tanto endereços individuais quanto um intervalo CIDR; use `--type ipAddress` para os endereços individuais e `--type cidrBlock` para o intervalo. Se sua organização exigir uma lista de acesso de API nas contas de serviço, adicione os mesmos IPs na página da conta de serviço no Atlas. Chamadas feitas a partir de um IP que não esteja na lista falham com `403`.

Etapa 2: Crie as identidades do Devin

Usuário do banco de dados

Leitura em bancos de dados de produção, leitura/gravação em um sandbox, com escopo restrito a clusters específicos: ```bash theme={null} atlas dbusers create \ --username devin-sessions \ --password "" \ --role read@analytics,read@billing,readWrite@devin_dev \ --scope \ --projectId ``` Sem `--scope`, o usuário consegue acessar todos os clusters do projeto. Use uma [função de banco de dados personalizada](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles/) quando as funções nativas não forem suficientes para definir esse limite. Gere a senha com um gerenciador de senhas e não a deixe no histórico do shell. Copie a connection string desse usuário; não entregue ao Devin o usuário administrador do cluster.

Conta de serviço (somente se o Devin precisar do plano de controle)

No Atlas, acesse **Identity & Access > Applications** no nível da organização. Comece com acesso somente leitura e escolha o menor tempo de validade do segredo do cliente que sua política de rotação permitir. | | Roles | Motivo | | - | - | - | | **Conceder** | `ORG_MEMBER` na organização; `GROUP_READ_ONLY` e `GROUP_DATA_ACCESS_READ_ONLY` em cada projeto | Base somente leitura | | **Adicionar somente se necessário** | `GROUP_SEARCH_INDEX_EDITOR` | O Devin gerencia índices de Search | | **Nunca** | `GROUP_OWNER`, `GROUP_DATABASE_ACCESS_ADMIN` | Qualquer uma delas permite que o Devin amplie o próprio acesso | A linha **Nunca** é especialmente importante na Opção B. Se a conta de serviço puder criar usuários de banco de dados, a ferramenta `atlas-connect-cluster` do servidor MCP criará um usuário temporário com acesso a todo o cluster (`readAnyDatabase`, ou `readWriteAnyDatabase` sem `--readOnly`), contornando as funções por banco de dados em `devin-sessions`. Esse usuário permanece ativo por 4 horas, a menos que a ferramenta de desconexão do MCP o exclua antes.

Etapa 3: Conectar o Devin

Opção A: CLI em um blueprint

1. Adicione os Devin Secrets

Na aba **Secrets** do blueprint: | Segredo | Valor | | - | - | | `MONGODB_URI` | A connection string de `devin-sessions`, por exemplo, `mongodb+srv://devin-sessions:@cluster0.abcde.mongodb.net/`. Aplique percent-encoding à senha. | | `MONGODB_ATLAS_CLIENT_ID` | Client ID da conta de serviço (`mdb_sa_id_...`), se você usar o plano de controle | | `MONGODB_ATLAS_CLIENT_SECRET` | Client secret da conta de serviço | | `MONGODB_ATLAS_PROJECT_ID` | ID do projeto padrão | Os segredos são injetados a cada sessão, então alterar (rotacionar) um valor não exige um novo build. O Atlas CLI lê o client ID e o client secret dessas variáveis de ambiente, então não é preciso executar `atlas auth login`. No primeiro uso, ele armazena um token de acesso em cache em `~/.config/atlascli/config.toml`. Isso não é problema dentro de uma sessão, mas nunca crie esse arquivo em `initialize`.

2. Adicione o blueprint

```yaml theme={null} initialize: - name: Install the Atlas CLI and mongosh run: | curl -fsSL https://pgp.mongodb.com/server-8.0.asc \ | sudo gpg --batch --yes -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/8.0 multiverse" \ | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list sudo apt-get update sudo apt-get install -y mongodb-atlas-cli mongodb-mongosh atlas --version && mongosh --version knowledge: - name: mongodb-access contents: | Connect to MongoDB with `mongosh "$MONGODB_URI"`; the URI is a Devin Secret. The Atlas CLI authenticates as a service account from MONGODB_ATLAS_CLIENT_ID and MONGODB_ATLAS_CLIENT_SECRET, with MONGODB_ATLAS_PROJECT_ID as the default project. Do not run `atlas auth login`, do not ask for a username, password, or API key, and never write the connection string into a file, script, log, or PR. Production databases are read-only; write only to the devin_dev database. Ship schema, index, and migration changes through a pull request. ``` Substitua `jammy` se a sua imagem não for Ubuntu 22.04. O bloco `knowledge` é mais importante do que a instalação: sem ele, as sessões executam `atlas auth login` (um fluxo no navegador que ninguém consegue concluir) ou pedem uma connection string que já está no ambiente. Não grave credenciais em disco no `initialize`. Um `~/.mongoshrc.js`, um `~/.config/atlascli/config.toml` ou uma URI exportada no `~/.bashrc` acaba indo parar no snapshot e é compartilhado por todas as sessões futuras.

3. Faça o build do snapshot

Salve o blueprint, aguarde o status **Success** e inicie uma nova sessão. As sessões já abertas continuam com o snapshot antigo.

Opção B: servidor MCP do MongoDB

O [`mongodb-mcp-server`](https://github.com/mongodb-js/mongodb-mcp-server) oficial é executado como um processo local dentro da sessão e usa as identidades da Etapa 2. Para contar com as proteções dele, adicione-o como um servidor MCP personalizado (**Customize > MCPs > Add MCP > Adicionar um MCP personalizado**, transporte **STDIO**) em vez de usar o plugin `mongodb` do marketplace, cujo manifesto não expõe `--readOnly` nem `--indexCheck`. | Campo | Valor | | - | - | | Command | `npx` | | Arguments | `-y mongodb-mcp-server@ --readOnly --indexCheck` | | Environment | `MDB_MCP_CONNECTION_STRING` (mesmo valor de `MONGODB_URI`); opcionalmente, `MDB_MCP_API_CLIENT_ID` e `MDB_MCP_API_CLIENT_SECRET` para as ferramentas do Atlas | Fixe `` em uma versão que você já testou, pois o `npx` baixa o pacote a cada início de sessão. Com a conta de serviço somente leitura da Etapa 2, `atlas-connect-cluster` retorna `401`; o Devin acessa os dados pela conexão `preconfigured` definida em `MDB_MCP_CONNECTION_STRING`, que é o caminho esperado. * `--readOnly` impede o registro das ferramentas de criação, atualização e exclusão, e rejeita agregações que contenham `$out` ou `$merge`. Sem essa opção, essas agregações são executadas após um prompt de confirmação, ou sem confirmação se o cliente MCP não oferecer suporte a prompts. Use-a em tudo que apontar para produção. * `--indexCheck` rejeita consultas cujo plano seja uma varredura de coleção. Trata-se de uma proteção de desempenho; se o próprio `explain` falhar, a consulta é executada mesmo assim. O servidor requer Node `^20.19.0 || ^22.13.0 || >=24.0.0`. Verifique `node --version` em uma sessão; se a versão for mais antiga ou se o `npx` não estiver no path visto pelo processo MCP, adicione o Node ao blueprint: ```yaml theme={null} initialize: - name: Install Node.js for the MongoDB MCP server uses: github.com/actions/setup-node@v4 with: node-version: "22" ``` Mantenha o usuário de banco de dados somente leitura mesmo usando `--readOnly`. O Devin também pode executar `mongosh "$MONGODB_URI"` com o mesmo usuário, então são as funções desse usuário que de fato garantem o limite de acesso.

Opção C: plugin do MongoDB Atlas

O [plugin](/pt-BR/product-guides/plugins) **MongoDB Atlas** conecta o Devin ao servidor MCP hospedado do MongoDB (`mcp.mongodb.com`) e instala as skills de agente do MongoDB. O Devin atua com as funções do Atlas do usuário que faz login, limitadas pelo modo de acesso de clientes de IA da organização. 1. Um Organization Owner ativa o [acesso de clientes de IA](https://www.mongodb.com/docs/mcp-server/remote-mcp/manage-ai-client-access/) (**Organization Settings > App Connections**) e define o modo de acesso como **Read**, para que as ferramentas de escrita não sejam registradas. Essa configuração vale para todos os clientes de IA da organização, não apenas para o Devin. 2. Crie um usuário do Atlas dedicado ao Devin com `GROUP_READ_ONLY` e `GROUP_DATA_ACCESS_READ_ONLY`, apenas nos projetos que ele tem permissão para ler. `GROUP_DATA_ACCESS_READ_ONLY` permite ler documentos em todos os bancos de dados do projeto, ou seja, esse acesso é mais amplo que o do usuário `devin-sessions`. 3. Instale o plugin e conclua o login OAuth uma única vez em **Customize > MCPs**, conectado como esse usuário, e não com sua própria conta. 4. Quando estiver funcionando, [fixe o plugin em um commit](/pt-BR/product-guides/plugins#pinning-a-plugin). O tráfego se origina da infraestrutura hospedada do MongoDB e do Devin, e não da sessão, então as listas de IPs da etapa 1 e sua network policy não se aplicam. O acesso expira após 7 dias de inatividade ou 30 dias após o login, o que ocorrer primeiro; nesse caso, faça login novamente. Revogar o acesso não exclui os usuários de banco de dados nem outros artefatos criados pelo cliente, por isso faça uma auditoria deles.

Rebuilds e fixação de versões

O blueprint instala o que o `apt` resolver no momento do build, e o `npx` da Opção B baixa o `mongodb-mcp-server` a cada início de sessão. Fixe as versões de ambos (`mongodb-atlas-cli=`, `mongodb-mongosh=`, `mongodb-mcp-server@`) assim que estiverem funcionando e só as atualize de forma intencional. Rotacionar um segredo não exige rebuild; já alterar uma ferramenta instalada exige.

Etapa 4: Defina as permissões

A autenticação define quem o Devin é; as roles do banco de dados e do Atlas definem o que ele pode acessar. As flags do MCP e as instruções de Knowledge são facilidades adicionais, não o limite de segurança. | Perfil | Trabalho típico | Roles de usuário do banco de dados | Roles da conta de serviço | | - | - | - | - | | **Explore** (comece aqui) | Documentar o schema, explicar uma query lenta, propor um índice em um PR | `read` nos bancos de dados de produção | `GROUP_READ_ONLY` + `GROUP_DATA_ACCESS_READ_ONLY` | | **Build** | Escrever e testar migrações, pipelines e dados de seed com dados de estrutura realista | Explore, mais `readWrite@devin_dev` | Igual ao Explore | | **Operate** | Criar índices ou índices do Atlas Search em coleções específicas | Explore, mais uma role personalizada que concede `createIndex` nessas coleções | Explore, mais `GROUP_SEARCH_INDEX_EDITOR` | No Explore, os índices sugeridos exigem apenas `GROUP_READ_ONLY` (os valores das queries são retornados mascarados). A lista de queries lentas, os valores de exemplo das queries e o download de logs também exigem `GROUP_DATA_ACCESS_READ_ONLY`; o `GROUP_DATA_ACCESS_READ_WRITE` solicitado pela ajuda da Atlas CLI não é necessário. Somente com `GROUP_READ_ONLY`, a ferramenta `atlas-get-performance-advisor` do MCP retorna "No slow query logs found" em vez de `401`; portanto, um resultado vazio pode indicar um problema de role. O código continua sendo entregue por meio de pull requests. O Devin lê a produção para entender o problema e valida a correção em `devin_dev`; a migração ou o índice segue pelo seu processo normal de revisão.

Etapa 5: Verificar

Inicie uma nova sessão e peça ao Devin para executar: **Conectividade.** Qual usuário, quais funções e (se configurada) se a autenticação da Atlas CLI funciona: ```bash theme={null} mongosh "$MONGODB_URI" --quiet --eval 'JSON.stringify(db.runCommand({connectionStatus: 1}), null, 2)' atlas clusters list --projectId "$MONGODB_ATLAS_PROJECT_ID" ``` **Limite.** O primeiro insert deve falhar (`not authorized on to execute command` em clusters dedicados, `user is not allowed to do action [insert] on [.devin_probe]` em M0/Flex); já o segundo deve funcionar: ```bash theme={null} mongosh "$MONGODB_URI" --quiet --eval 'db.getSiblingDB("").devin_probe.insertOne({probe: 1})' mongosh "$MONGODB_URI" --quiet --eval 'db.getSiblingDB("devin_dev").devin_probe.insertOne({probe: 1}); db.getSiblingDB("devin_dev").devin_probe.drop()' ``` Verifique se as funções em `connectionStatus` correspondem ao perfil que você concedeu; uma conexão aberta, por si só, não comprova muita coisa. Para o servidor MCP, peça ao Devin que liste os bancos de dados usando as ferramentas MCP (ele usa a conexão `preconfigured`) e, depois, que insira um documento: com `--readOnly`, a ferramenta `insert-many` não existe, e uma agregação com `$out` é recusada.

Solução de problemas

| Sintoma | Aplica-se a | Causa e correção | | - | - | - | | A conexão expira ou o erro menciona a lista de acesso por IP | A, B | Os IPs do Devin não estão na lista de acesso por IP do projeto (a falha mais comum) ou sua network policy bloqueia `*.mongodb.net` na porta TCP 27017. | | `querySrv ENOTFOUND _mongodb._tcp.` | A, B | DNS bloqueado ou hostname incorreto. Permita `*.mongodb.net` na network policy. | | `Authentication failed` ou `bad auth : authentication failed` | A, B | Senha incorreta ou `authSource` incorreto. | | `MongoParseError: Protocol and host list are required` | A, B | A senha na URI contém `@`, `/` ou `+` sem percent-encoding. Codifique-a; isso não é um erro de autenticação. | | `not authorized on to execute command` ou `user is not allowed to do action` | A, B | Autenticado, mas sem permissão. É o comportamento esperado quando o Devin tenta gravar em produção; caso contrário, amplie as funções do usuário. | | A Atlas CLI exibe `unauthorized` ou sugere `atlas auth login` | A, B | Os segredos da service account estão ausentes, incorretos ou expirados, ou a função da service account não permite essa ação (o servidor MCP também informa isso como credenciais inválidas). Verifique a função antes de rotacionar os segredos. Não execute `atlas auth login`. | | A Atlas CLI retorna `403` após a autenticação | A, B | Os IPs do Devin não estão na lista de acesso à API da service account (Etapa 1). | | O Devin executa `atlas auth login` ou pede uma connection string | A | O bloco `knowledge` está ausente ou os segredos não estão no blueprint usado pela sessão. | | O build do blueprint falha no `apt-get` ou o servidor MCP não inicia | A, B | A network policy não inclui `pgp.mongodb.com`, `repo.mongodb.org`, `registry.npmjs.org` ou `nodejs.org`; ou a versão do Node é anterior à 20.19 (execute `node --version`). | | O MCP rejeita uma consulta por não usar um índice | B | O `--indexCheck` está funcionando como deveria. Adicione o índice em um PR ou execute a consulta com `mongosh` em `devin_dev`. Consultas que exigem um índice com collation são sempre rejeitadas: a ferramenta `find` do MCP não aceita argumento de collation. | | Ferramentas do Atlas ausentes ou ferramentas de escrita visíveis | C | O acesso de clientes de IA está desativado, o modo de acesso é **Read and write** ou o usuário do Atlas autenticado tem funções mais amplas do que o previsto. Verifique o modo em **App Connections** e quem concluiu o login OAuth. | | As credenciais funcionam em uma sessão, mas não na seguinte | A | O snapshot contém um arquivo de configuração obsoleto de um `initialize` anterior. Remova-o do blueprint e faça o rebuild. |

Limitações

**É obrigatório usar credenciais armazenadas.** O [token OIDC](/pt-BR/product-guides/oidc) de curta duração do Devin ainda não pode ser usado com o MongoDB: a Administration API aceita apenas segredos de service account ou chaves de API. O [Workload Identity Federation](https://www.mongodb.com/docs/atlas/workload-oidc/) do Atlas cobre o plano de dados em clusters dedicados, mas exige um callback de token no nível do driver e ainda não foi testado com o emissor do Devin. Se quiser experimentar, fale com a equipe responsável pela sua conta. **MongoDB auto-hospedado.** As etapas do plano de dados (usuário do banco de dados, `MONGODB_URI`, `mongosh`, servidor MCP) continuam valendo sem alterações. Não há service account do Atlas nem lista de acesso por IP; o acesso à rede passa pela sua [VPN](/pt-BR/onboard-devin/vpn) ou pela sua própria lista de permissões.

Suporte

Para questões relacionadas ao Atlas, consulte a [documentação de segurança do Atlas](https://www.mongodb.com/docs/atlas/setup-cluster-security/) e a [documentação do MongoDB MCP Server](https://www.mongodb.com/docs/mcp-server/). Para questões relacionadas ao Devin, entre em contato pelo [support@cognition.ai](mailto:support@cognition.ai) ou com a equipe responsável pela sua conta. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.