Connettere Devin a MongoDB

Devin può lavorare con i tuoi dati MongoDB come farebbe un ingegnere con una stringa di connessione in sola lettura: esaminare cosa contengono davvero le collezioni, capire perché una query è lenta, provare una migrazione in un database sandbox e aprire una pull request (PR). Questa guida spiega come configurare il tutto con identità create appositamente per Devin, in modo che non operi mai con le credenziali di uno dei tuoi ingegneri.

Tutto resta nel tuo account Atlas: un utente del database, un account di servizio, gli strumenti MongoDB installati tramite un blueprint dell’ambiente e, facoltativamente, un server MCP. Parti con permessi ristretti (produzione in sola lettura) e amplia i ruoli in un secondo momento: sono i ruoli a delimitare l’accesso e puoi modificarli in Atlas senza intervenire su Devin.

Due piani, due identità

Piano	A cosa accede	Identità di Devin	Credenziale
Piano dati	Database, documenti, indici, `explain()`	Un utente del database	Nome utente e password in una stringa di connessione
Control plane	Cluster, indici di Search, Performance Advisor, log delle query lente, utenti del database, elenchi di accesso	Un account di servizio Atlas	Client ID e client secret OAuth 2.0

Un utente del database non può chiamare l’Atlas Administration API e un account di servizio non può leggere documenti tramite l’API. La maggior parte dei team parte dal solo piano dati e aggiunge l’account di servizio quando Devin ha bisogno di Performance Advisor o dei log delle query lente (cluster dedicati, da M10 in su). Due avvertenze:

Un account di servizio in grado di creare utenti del database (GROUP_OWNER, GROUP_DATABASE_ACCESS_ADMIN) può crearsi autonomamente un’identità sul piano dati. Il server MCP di MongoDB fa proprio questo quando gli si chiede di connettersi a un cluster (Opzione B).
I dati delle query lente contengono i valori letterali delle query.

Scegliere come si connette Devin

Tutti e tre i percorsi usano lo stesso accesso alla rete (Passaggio 1) e le stesse identità (Passaggio 2); cambia solo ciò a cui Devin ha accesso diretto.

Percorso	Ideale per	Configurazione
Opzione A: CLI in un blueprint	Attività che Devin esegue e ripete in un repo: migrazioni, backfill, dati seed, test su dati con struttura realistica	Quattro Devin Secrets e un breve blueprint. Inizia da qui.
Opzione B: server MCP di MongoDB	Individuazione dello schema e analisi di query e indici tramite strumenti, con le barriere di sicurezza `--readOnly` e `--indexCheck`	Un server MCP STDIO personalizzato che usa le stesse credenziali. Si aggiunge all’Opzione A.
Opzione C: plugin MongoDB Atlas	Domande su Atlas e letture a livello di progetto, senza salvare una credenziale MongoDB nella sessione	Plugin dal marketplace, login OAuth come utente Atlas dedicato; modalità di accesso all’org impostata su Read.

Perché connettere Devin a MongoDB?

Lo schema risiede nei documenti. MongoDB non dispone di un information_schema e i modelli Mongoose o Prisma tendono a discostarsi da ciò che è effettivamente memorizzato. Devin campiona le collezioni live e lavora sulla loro struttura reale.
Il ciclo di ottimizzazione delle query lente si chiude in una sola sessione. Devin legge Performance Advisor e il log delle query lente, esegue explain() sulla collezione reale, individua il codice che esegue la query e apre una pull request (PR) con la soluzione e l’indice proposto.
I ruoli dell’utente del database stabiliscono a cosa può accedere Devin. Inizia con l’accesso in sola lettura in produzione e una sandbox devin_dev per le scritture: ogni azione viene registrata nei log di Atlas con l’identità dedicata di Devin.

Prerequisiti

Atlas

Un progetto con un cluster.
Il ruolo Organization Owner per creare un account di servizio; il ruolo Project Owner per l’utente del database e gli elenchi di accesso.

Devin

Autorizzazione a modificare il blueprint dell’ambiente e ad aggiungere segreti.
Per i percorsi MCP, l’autorizzazione Gestire server MCP.

Rete

Gli IP di Devin inseriti nell’elenco di accesso IP del progetto (Passaggio 1).
Se utilizzi una network policy di Devin, consenti *.mongodb.net e cloud.mongodb.com, oltre agli host da cui il blueprint esegue le installazioni: pgp.mongodb.com e repo.mongodb.org (Opzione A), registry.npmjs.org e nodejs.org (Opzione B). Il driver si connette sulla porta 27017, non sulla 443; le voci della policy sono hostname o CIDR, quindi non c’è alcuna porta da impostare. Anche le build degli snapshot vengono eseguite con la stessa policy.

Passaggio 1: aprire l’accesso alla rete

Atlas rifiuta le connessioni provenienti da IP non inclusi nell’elenco di accesso IP del progetto. Aggiungi gli IP elencati in allowlisting degli IP, senza andare a memoria. I tenant dedicati dispongono di indirizzi di uscita propri: verificali con il tuo account team.

atlas accessLists create <ip> --type ipAddress --comment "Devin" --projectId <project-id>
atlas accessLists create <cidr> --type cidrBlock --comment "Devin" --projectId <project-id>

L’elenco contiene sia indirizzi singoli sia un intervallo CIDR; usa --type ipAddress per gli indirizzi singoli e --type cidrBlock per l’intervallo. Se la tua organizzazione richiede un elenco di accesso API per gli account di servizio, aggiungi gli stessi IP nella pagina dell’account di servizio in Atlas. Le chiamate provenienti da un IP non incluso nell’elenco non vanno a buon fine e restituiscono 403.

Passaggio 2: Crea le identità di Devin

Utente del database

Accesso in lettura ai database di produzione, in lettura/scrittura in una sandbox, con ambito limitato a cluster specifici:

atlas dbusers create \
  --username devin-sessions \
  --password "<generated-password>" \
  --role read@analytics,read@billing,readWrite@devin_dev \
  --scope <cluster-name> \
  --projectId <project-id>

Senza --scope l’utente può accedere a tutti i cluster del progetto. Usa un ruolo di database personalizzato quando i ruoli predefiniti non consentono di definire i limiti di accesso necessari. Genera la password con un password manager e non lasciarla nella cronologia della shell. Copia la stringa di connessione di questo utente; non fornire a Devin l’utente amministratore del cluster.

Account di servizio (solo se Devin ha bisogno del control plane)

In Atlas, vai su Identity & Access > Applications a livello di organizzazione. Inizia con l’accesso in sola lettura e scegli per il client secret la durata più breve compatibile con la tua politica di rotazione.

	Ruoli	Motivo
Concedi	`ORG_MEMBER` sull’organizzazione; `GROUP_READ_ONLY` e `GROUP_DATA_ACCESS_READ_ONLY` su ciascun progetto	Base in sola lettura
Aggiungi solo se necessario	`GROUP_SEARCH_INDEX_EDITOR`	Devin gestisce gli indici di Search
Mai	`GROUP_OWNER`, `GROUP_DATABASE_ACCESS_ADMIN`	Entrambi consentono a Devin di estendere i propri accessi

La riga Mai è particolarmente importante con l’Opzione B. Se l’account di servizio può creare utenti del database, lo strumento atlas-connect-cluster del server MCP crea un utente temporaneo sull’intero cluster (readAnyDatabase, oppure readWriteAnyDatabase senza --readOnly), aggirando i ruoli per singolo database su devin-sessions. Questo utente resta attivo per 4 ore, a meno che lo strumento di disconnessione MCP non lo elimini prima.

Passaggio 3: Connetti Devin

Opzione A: CLI in un blueprint

Aggiungi i segreti Devin

Nella scheda Segreti del blueprint:

Segreto	Valore
`MONGODB_URI`	La stringa di connessione di `devin-sessions`, ad es. `mongodb+srv://devin-sessions:<password>@cluster0.abcde.mongodb.net/`. Applica il percent-encoding alla password.
`MONGODB_ATLAS_CLIENT_ID`	Client ID dell’account di servizio (`mdb_sa_id_...`), se usi il control plane
`MONGODB_ATLAS_CLIENT_SECRET`	Client secret dell’account di servizio
`MONGODB_ATLAS_PROJECT_ID`	ID del progetto predefinito

I segreti vengono iniettati in ogni sessione, quindi per ruotare un valore non serve una ricompilazione. L’Atlas CLI legge il client ID e il client secret da queste variabili d’ambiente, quindi non è necessario eseguire atlas auth login. Al primo utilizzo salva in cache un access token in ~/.config/atlascli/config.toml: va bene all’interno di una sessione, ma non creare mai quel file in initialize.

Aggiungi il blueprint

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.

Sostituisci jammy se la tua immagine non è Ubuntu 22.04. Il blocco knowledge è più importante dell’installazione: senza di esso, le sessioni eseguono atlas auth login (un flusso nel browser che nessuno può completare) oppure chiedono una stringa di connessione già presente nell’ambiente.

Non scrivere credenziali su disco in initialize. Un file ~/.mongoshrc.js o ~/.config/atlascli/config.toml, oppure un URI esportato in ~/.bashrc, finisce nello snapshot e viene condiviso da tutte le sessioni future.

Esegui la build dello snapshot

Salva il blueprint, attendi lo stato Success, quindi avvia una nuova sessione. Le sessioni già aperte continuano a usare lo snapshot precedente.

Opzione B: server MCP di MongoDB

Il server ufficiale mongodb-mcp-server viene eseguito come processo locale all’interno della sessione e utilizza le identità del passaggio 2. Per sfruttarne le barriere di sicurezza, aggiungilo come server MCP personalizzato (Customize > MCPs > Add MCP > Add custom MCP, transport STDIO) anziché tramite il plugin mongodb del marketplace, il cui manifest non espone --readOnly né --indexCheck.

Campo	Valore
Command	`npx`
Arguments	`-y mongodb-mcp-server@<version> --readOnly --indexCheck`
Environment	`MDB_MCP_CONNECTION_STRING` (stesso valore di `MONGODB_URI`); facoltativamente `MDB_MCP_API_CLIENT_ID` e `MDB_MCP_API_CLIENT_SECRET` per gli strumenti Atlas

Blocca <version> su una release che hai già testato: npx scarica il pacchetto a ogni avvio di sessione. Con l’account di servizio in sola lettura del passaggio 2, atlas-connect-cluster restituisce 401; Devin accede ai dati tramite la connessione preconfigured definita da MDB_MCP_CONNECTION_STRING, che è il percorso previsto.

--readOnly salta la registrazione degli strumenti di creazione, aggiornamento ed eliminazione e rifiuta le aggregazioni che contengono $out o $merge. Senza questa opzione, tali aggregazioni vengono eseguite dopo una richiesta di conferma, oppure senza alcuna conferma se il client MCP non supporta i prompt. Usala per qualsiasi configurazione che punti alla produzione.
--indexCheck rifiuta le query il cui piano prevede una scansione completa della collezione. Si tratta di una barriera di sicurezza per le prestazioni: se lo stesso explain non riesce, la query viene comunque eseguita.

Il server richiede Node ^20.19.0 || ^22.13.0 || >=24.0.0. Verifica l’output di node --version in una sessione; se la versione è precedente, o se npx non è nel path visibile al processo MCP, aggiungi Node al blueprint:

initialize:
  - name: Install Node.js for the MongoDB MCP server
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

Mantieni l’utente del database in sola lettura anche con --readOnly. Devin può eseguire anche mongosh "$MONGODB_URI" con lo stesso utente, quindi la vera barriera di protezione sono i ruoli dell’utente.

Opzione C: plugin MongoDB Atlas

Il plugin MongoDB Atlas collega Devin al server MCP ospitato da MongoDB (mcp.mongodb.com) e installa le skill per agenti di MongoDB. Devin opera con i ruoli Atlas dell’utente che effettua l’accesso, entro i limiti stabiliti dalla modalità di accesso dei client AI dell’organizzazione.

Un Organization Owner abilita l’accesso dei client AI (Organization Settings > App Connections) e imposta la modalità di accesso su Read, così gli strumenti di scrittura non vengono registrati. L’impostazione vale per tutti i client AI dell’organizzazione, non solo per Devin.
Crea un utente Atlas dedicato a Devin con GROUP_READ_ONLY e GROUP_DATA_ACCESS_READ_ONLY, solo nei progetti a cui deve avere accesso in lettura. GROUP_DATA_ACCESS_READ_ONLY consente di leggere i documenti di tutti i database del progetto, quindi questo accesso è più ampio di quello dell’utente devin-sessions.
Installa il plugin e completa una sola volta l’accesso OAuth in Customize > MCPs, autenticandoti come quell’utente e non con il tuo account.
Dopo averne verificato il funzionamento, blocca il plugin su un commit.

Il traffico proviene dall’infrastruttura ospitata di MongoDB e di Devin, non dalla sessione, quindi gli elenchi di IP del Passaggio 1 e la tua network policy non vengono applicati. L’accesso scade dopo 7 giorni di inattività o 30 giorni dal login, a seconda di quale condizione si verifichi prima; in tal caso, accedi di nuovo. La revoca dell’accesso non elimina gli utenti del database né gli altri artefatti creati dal client, quindi controllali.

Ricompilazioni e blocco delle versioni

Il blueprint installa la versione che apt risolve al momento della build, e con l’Opzione B npx scarica mongodb-mcp-server a ogni avvio di sessione. Una volta verificato che funzionano, bloccate le versioni di entrambi (mongodb-atlas-cli=<version>, mongodb-mongosh=<version>, mongodb-mcp-server@<version>) e aggiornatele solo in modo intenzionale. La rotazione di un segreto non richiede una ricompilazione, mentre la modifica di uno strumento installato sì.

Passaggio 4: Impostare le autorizzazioni

L’autenticazione stabilisce chi è Devin; i ruoli del database e di Atlas stabiliscono su cosa può intervenire. I flag MCP e le istruzioni di Knowledge sono semplici agevolazioni aggiuntive, non il vero perimetro di sicurezza.

Profilo	Attività tipiche	Ruoli dell’utente del database	Ruoli dell’account di servizio
Explore (inizia da qui)	Documentare lo schema, spiegare una query lenta, proporre un indice in una PR	`read` sui database di produzione	`GROUP_READ_ONLY` + `GROUP_DATA_ACCESS_READ_ONLY`
Build	Scrivere e testare migrazioni, pipeline e dati di seed su dati con struttura realistica	Explore, più `readWrite@devin_dev`	Come Explore
Operate	Creare indici o indici Atlas Search su collezioni specifiche	Explore, più un ruolo personalizzato che concede `createIndex` su tali collezioni	Explore, più `GROUP_SEARCH_INDEX_EDITOR`

Per Explore, gli indici suggeriti richiedono solo GROUP_READ_ONLY (i valori delle query vengono restituiti mascherati). L’elenco delle query lente, i valori di esempio delle query e il download dei log richiedono anche GROUP_DATA_ACCESS_READ_ONLY; il ruolo GROUP_DATA_ACCESS_READ_WRITE indicato nella guida dell’Atlas CLI non è necessario. Con il solo GROUP_READ_ONLY, lo strumento MCP atlas-get-performance-advisor restituisce “No slow query logs found” anziché l’errore 401: un risultato vuoto potrebbe quindi dipendere da un problema di ruoli.

Il codice passa comunque attraverso le pull request. Devin legge i dati di produzione per comprendere il problema e verifica la soluzione in devin_dev; la migrazione o l’indice vengono poi integrati tramite il tuo normale processo di revisione.

Passaggio 5: Verifica

Avvia una nuova sessione e chiedi a Devin di eseguire: Connettività. Quale utente e quali ruoli vengono usati e (se configurata) se l’Atlas CLI si autentica correttamente:

mongosh "$MONGODB_URI" --quiet --eval 'JSON.stringify(db.runCommand({connectionStatus: 1}), null, 2)'
atlas clusters list --projectId "$MONGODB_ATLAS_PROJECT_ID"

Confine di accesso. Il primo inserimento dovrebbe non riuscire (not authorized on <prod-db> to execute command sui cluster dedicati, user is not allowed to do action [insert] on [<prod-db>.devin_probe] su M0/Flex), mentre il secondo dovrebbe andare a buon fine:

mongosh "$MONGODB_URI" --quiet --eval 'db.getSiblingDB("<prod-db>").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()'

Verifica che i ruoli in connectionStatus corrispondano al profilo che hai assegnato: una connessione aperta, di per sé, dimostra poco. Per il server MCP, chiedi a Devin di elencare i database tramite gli strumenti MCP (usa la connessione preconfigured), quindi di inserire un documento: con --readOnly lo strumento insert-many non è disponibile e un’aggregazione con $out viene rifiutata.

Risoluzione dei problemi

Sintomo	Si applica a	Causa e soluzione
La connessione va in timeout oppure l’errore fa riferimento all’elenco di accesso IP	A, B	Gli IP di Devin non sono presenti nell’elenco di accesso IP del progetto (la causa più comune), oppure la tua network policy blocca `*.mongodb.net` sulla porta TCP 27017.
`querySrv ENOTFOUND _mongodb._tcp.<host>`	A, B	DNS bloccato o hostname errato. Consenti `*.mongodb.net` nella network policy.
`Authentication failed` o `bad auth : authentication failed`	A, B	Password errata o `authSource` errato.
`MongoParseError: Protocol and host list are required`	A, B	La password nell’URI contiene `@`, `/` o `+` e non è codificata in percent-encoding. Codificala: non si tratta di un errore di autenticazione.
`not authorized on <db> to execute command` o `user is not allowed to do action`	A, B	Accesso riuscito, ma senza i permessi necessari. È il comportamento previsto quando Devin scrive in produzione; in caso contrario, amplia i ruoli dell’utente.
L’Atlas CLI restituisce `unauthorized` o suggerisce `atlas auth login`	A, B	I segreti dell’account di servizio sono mancanti, errati o scaduti, oppure il ruolo dell’account di servizio non consente quell’azione (anche il server MCP la segnala come credenziali non valide). Verifica il ruolo prima di ruotare i segreti. Non eseguire `atlas auth login`.
L’Atlas CLI restituisce `403` dopo l’autenticazione	A, B	Nell’elenco di accesso API dell’account di servizio mancano gli IP di Devin (Passaggio 1).
Devin esegue `atlas auth login` o chiede una stringa di connessione	A	Manca il blocco `knowledge`, oppure i segreti non sono configurati nel blueprint usato dalla sessione.
La build del blueprint non riesce su `apt-get`, oppure il server MCP non si avvia	A, B	Nella network policy mancano `pgp.mongodb.com`, `repo.mongodb.org`, `registry.npmjs.org` o `nodejs.org`; oppure la versione di Node è precedente alla 20.19 (esegui `node --version`).
Il server MCP rifiuta una query perché non usa un indice	B	`--indexCheck` sta facendo il suo lavoro. Aggiungi l’indice in una PR, oppure esegui la query con `mongosh` su `devin_dev`. Le query che richiedono un indice con collation vengono sempre rifiutate: lo strumento MCP `find` non prevede un argomento per la collation.
Strumenti Atlas mancanti o presenza di strumenti di scrittura	C	L’accesso dei client AI è disabilitato, oppure la modalità di accesso è Read and write, oppure l’utente Atlas autenticato ha ruoli più ampi del previsto. Verifica la modalità in App Connections e controlla chi ha completato l’accesso OAuth.
Le credenziali funzionano in una sessione ma non in quella successiva	A	Nello snapshot è rimasto un file di configurazione obsoleto creato da un precedente `initialize`. Rimuovilo dal blueprint ed esegui di nuovo la ricompilazione.

Limitazioni

Sono necessarie credenziali archiviate. Al momento il token OIDC di breve durata di Devin non può essere usato con MongoDB: l’Administration API accetta solo segreti di account di servizio o chiavi API. La Workload Identity Federation di Atlas copre il piano dati sui cluster dedicati, ma richiede una callback del token a livello di driver e non è stata testata con l’issuer di Devin. Se vuoi provarla, contatta il tuo account team. MongoDB self-hosted. I passaggi relativi al piano dati (utente del database, MONGODB_URI, mongosh, server MCP) restano invariati. Non esistono un account di servizio Atlas né un elenco di accesso IP: l’accesso alla rete avviene tramite la tua VPN o una tua allowlist.

Supporto

Per quanto riguarda Atlas, consulta la documentazione sulla sicurezza di Atlas e la documentazione del server MCP di MongoDB. Per quanto riguarda Devin, contatta support@cognition.ai o il tuo account team.

Introduzione

Guide fondamentali

Introduzione a Devin

Lavorare con Devin

Guide sul prodotto

Integrazioni

Admin

Note di rilascio

Connettere Devin a MongoDB

Due piani, due identità

Scegliere come si connette Devin

Perché connettere Devin a MongoDB?

Prerequisiti

Passaggio 1: aprire l’accesso alla rete

Passaggio 2: Crea le identità di Devin

Utente del database

Account di servizio (solo se Devin ha bisogno del control plane)

Passaggio 3: Connetti Devin

Opzione A: CLI in un blueprint

Aggiungi i segreti Devin

Aggiungi il blueprint

Esegui la build dello snapshot

Opzione B: server MCP di MongoDB

Opzione C: plugin MongoDB Atlas

Ricompilazioni e blocco delle versioni

Passaggio 4: Impostare le autorizzazioni

Passaggio 5: Verifica

Risoluzione dei problemi

Limitazioni

Supporto

​Due piani, due identità

​Scegliere come si connette Devin

​Perché connettere Devin a MongoDB?

​Prerequisiti

​Passaggio 1: aprire l’accesso alla rete

​Passaggio 2: Crea le identità di Devin

​Utente del database

​Account di servizio (solo se Devin ha bisogno del control plane)

​Passaggio 3: Connetti Devin

​Opzione A: CLI in un blueprint

​ Aggiungi i segreti Devin

​ Aggiungi il blueprint

​ Esegui la build dello snapshot

​Opzione B: server MCP di MongoDB

​Opzione C: plugin MongoDB Atlas

​Ricompilazioni e blocco delle versioni

​Passaggio 4: Impostare le autorizzazioni

​Passaggio 5: Verifica

​Risoluzione dei problemi

​Limitazioni

​Supporto

Due piani, due identità

Scegliere come si connette Devin

Perché connettere Devin a MongoDB?

Prerequisiti

Passaggio 1: aprire l’accesso alla rete

Passaggio 2: Crea le identità di Devin

Utente del database

Account di servizio (solo se Devin ha bisogno del control plane)

Passaggio 3: Connetti Devin

Opzione A: CLI in un blueprint

Aggiungi i segreti Devin

Aggiungi il blueprint

Esegui la build dello snapshot

Opzione B: server MCP di MongoDB

Opzione C: plugin MongoDB Atlas

Ricompilazioni e blocco delle versioni

Passaggio 4: Impostare le autorizzazioni

Passaggio 5: Verifica

Risoluzione dei problemi

Limitazioni

Supporto