mongodb

Restart MongoDB Commands !MongoDB Logo It’s not entirely clear how to quickly start, stop and restart MongoDB with a command line, so I’ve documented it here based on the need for a simple, straightforward approach. MongoDB Commands Use the following commands to start, stop or restart MongoDB. Mac OS On Mac OS the installation process for MongoDB’s Community Edition uses the Homebrew brew package manager with the help of the official MongoDB tap. Starting, stopping and restarting MongoDB on a Mac involves using brew services. Start brew services start mongodb-community@6.0 Stop brew services stop mongodb-community@6.0 Restart brew services restart mongodb-community@6.0 Ubuntu/Debian MongoDB can be managed on linux machines in two ways: 1. service command 2. systemctl command service is used for running init scripts from the terminal. systemctl is a newer initialization system that aims to replace SysVInit. Most Linux distributions such as Debian and Red Hat are already using SystemD as their init system out of the box, so I’m including both here for reference. Start For systemd: sudo systemctl start mongod Or for service: sudo service mongod start Stop For systemd: sudo systemctl stop mongod Or for service: sudo service mongod stop Restart For systemd: sudo systemctl restart mongod Or for service: sudo service mongod restart Windows I’ve never used MongoDB in a Windows IIS environment, but for reference here’s what MongoDB has documented for starting, stopping and restarting the service. Start In the Windows Services console right-click on the MongoDB service and click Start. Stop In the Windows Services console right-click on the MongoDB service and click Stop. Restart In the Windows Services console right-click on the MongoDB service and click Start/Restart.

How to Deploy Your First Agent to MongoDB Atlas Agent Engine _This article was written by Damilola Oladele._ Imagine you built an employee onboarding assistant agent for your company. The agent answers questions about company policies, guides new employees through onboarding, and provides role-specific training. As employees begin using the agent, you encounter a few challenges. The agent cannot remember previous conversations, so employees must repeat information they have already provided. It also struggles to retrieve accurate answers from company documents and sometimes recommends training that employees have already completed. You might also want to monitor its behavior and ensure it only accesses information that each employee is authorized to see. A common approach to addressing these challenges is to combine several systems. You might use a vector database to retrieve company documents and a separate database to store conversation history. An agent framework would coordinate workflows, while an observability platform would monitor agent execution. You would also need infrastructure to run the agent and enforce security policies. While this approach works, integrating and maintaining these systems introduces additional complexity. So instead of building and managing these systems separately, you can use MongoDB Atlas Agent Engine (Agent Engine). It provides a unified platform that runs AI agents, stores conversation history, manages long-term memory, retrieves relevant information, and monitors agent execution. This tutorial helps you get started with Agent Engine. You'll install the agentengine CLI, scaffold a Hello World agent, test it locally, and deploy it to Agent Engine. The following flowchart outlines the local setup and deployment stages: !Image description The tutorial uses OpenRouter's free tier and a free Atlas M0 cluster, so you don't need a credit card. > Note: Agent Engine is in public preview. MongoDB intends it for evaluation and prototyping, and doesn't recommend production deployments during preview. MongoDB expects breaking changes periodically. When your terminal output differs from this tutorial, trust your terminal. Prerequisites Before you start, make sure you have the following ready: - Operating system: macOS or Linux. - Git: Git installed on your machine - Docker Desktop: Docker Desktop installed and running on your machine. - Python: Version 3.1 or later installed on your machine. - Atlas cluster: A MongoDB Atlas account with a free M0 cluster. > Note: Agent Engine doesn't support Atlas free clusters. This tutorial turns off the memory feature and stores only a few short sessions, so it can run on an M0 cluster. For an agent that uses the memory feature, use a Flex cluster or higher. To learn more, see Set Up Atlas Resources and Atlas Free Cluster Limits. - Connection string: The connection string for your Atlas cluster. In Atlas, click Connect on your cluster, then select Drivers. Atlas prompts you to create a database user if you don't have one. - Voyage AI API key: An API key created in the same Atlas project as your cluster. To create one, follow these steps: 1. Sign in to your Atlas account, the same one as your M0 cluster. 2. Go to SERVICES > AI Model APIs. 3. Select Create model API key. 4. Give it a name, then select Create. 5. Copy the key immediately and store it somewhere safe. - OpenRouter account: A free OpenRouter account with an API key. Install the agentengine CLI The agentengine CLI creates, runs, and deploys your agent, so it's the first tool to set up. Download it from the CLI download page, and follow the instructions for your operating system. The page requires an Atlas sign-in. You can also open it from the Atlas UI, under SERVICES > Agent Engine > Open Agent Engine, then Authorize. When I first tried installing the CLI, the installation failed with a network error. If you encounter the same issue, try running the installer again or switching to the manual download tab on the same page. Confirm the installation: agentengine --version If the installation succeeds, the command displays the installed version, such as 0.1.120. Sign In to Atlas Agent Engine Now sign in with your Atlas login information to allow the CLI to access your Atlas account: agentengine auth login A sign-in URL opens in your browser. After you sign in, the terminal confirms it: Open the following URL to authenticate: https://agentengine.mongodb.com/auth/start?... Successfully logged in. Set Up Docker for Local Development After signing in to Agent Engine, set up Docker to run the agent locally in containers. Before you begin local development, check that Docker meets these three requirements: - Docker Desktop is installed on your machine. - The Docker daemon is running. Launching Docker Desktop starts it. - The docker command works in your terminal. Launch Docker Desktop, then check all three conditions at once: docker info If the command displays both client and server details, then Docker is ready. If your shell can't find docker, then the command isn't on your PATH. So add the directory containing the Docker CLI to your PATH, then try again. If the command runs but can't connect to the server, then make sure Docker Desktop has finished starting. Get a Free OpenRouter API Key Your agent needs a language model to generate responses. The next step is to obtain an LLM API key. OpenRouter provides one API for many models, including free ones, and you don't need a credit card to use it. Go to OpenRouter, create an account, and open your account settings. Create a new API key, copy it, and save it. You'll paste it when prompted in the next section. OpenRouter's free models have the following rate limits: - 20 requests per minute. - 50 requests per day for accounts that have never purchased credits, or 1,000 requests per day for accounts that have purchased at least $10 in credits. One message to your agent can trigger multiple model requests. This is because the agent calls the model, runs its tools, and calls the model again to generate a response. A 50-request daily allowance is enough for this tutorial. The Hello World agent calls tools to process your request, so its model must support tool calling. I chose nvidia/nemotron-3.5-lightning:free because it supports tool calling and is available on OpenRouter's free tier. To list every free model that supports tool calling, query OpenRouter's public models endpoint by running the following in your terminal: curl -sS https://openrouter.ai/api/v1/models | python3 -c " import json, sys for m in json.load(sys.stdin)['data']: if m['id'].endswith(':free') and 'tools' in (m.get('supported_parameters') or []): print(m['id']) " Any model in that list can run this agent. Scaffold a Hello World Agent With the tools ready, generate the agent and confirm it can reach its model before you start any containers. The agentengine create command builds the project directory from MongoDB's Hello World template. Typing back at any prompt returns you to the previous one: agentengine create Answer the prompts as follows: | Prompt | Answer | | --- | --- | | Starter template | Hello World Agent | | Framework and language | Google ADK + Python | | Application name | my-agent | | Local directory | accept the default | | LLM connection | OpenRouter | | Model or deployment name | nvidia/nemotron-3.5-lightning:free | | LLM API key | your OpenRouter key | | Enable memory for local dev | no | | External host access | accept the recommended egress option | | Smoke test | yes | After the prompts, the CLI reports what it generated and runs the smoke test: ✓ Created my-agent from the Hello World Agent (Google ADK) template ✓ Personalized app name, slug, module, and local defaults ✓ Applied the selected LLM connection to the agent source ✓ Wrote .env ✓ Declared network.egress for openrouter.ai:443 (Agent and Tool) This list covers the LLM only. Add other destinations in agent.yaml under network.egress, or later with `agentengine agent egress add <fqdn>:443`. ✓ Installed the Atlas Agent Engine skill for Codex, Copilot, and Claude Code ✓ Installed the Atlas Agent Engine docs skill. Ask your coding agent platform questions to retrieve current docs. Smoke test now? (one 'Hello' request from this machine, 10s timeout) [Y/n] y ✓ openrouter/nvidia/nemotron-3.5-lightning:free responded in 4.4s Next: 1. cd my-agent/agents/my-agent 2. agentengine dev up 3. When you're ready to deploy: agentengine deploy The final line, ✓ openrouter/nvidia/nemotron-3.5-lightning:free responded in 4.4s, confirms that the generated agent reached OpenRouter and received a response. That rules out key and network problems before Docker is involved. During my earlier setup attempt, the smoke test prompt returned an HTTP 401 (Unauthorized) error, even though my OpenRouter API key was valid. If you encounter the same error, don't assume that project creation failed. Continue with the instructions in the [Run the Agent Locally](#run-the-agent-locally) section. Explore the Hello World Agent The agentengine create command creates a my-agent project directory containing an agents/ directory, with your agent in a subdirectory. Your project structure looks like this: my-agent/ ├── project-config.yaml └── agents/ └── my-agent/ ├── agent.yaml ├── pyproject.toml ├── .env └── src/ └── agent_my_agent/ ├── main.py ├── llm.py ├── system_message.py └── tools.py The agent.yaml file tells Agent Engine what your agent is called, which tools it has, and where it can connect: # Human-readable app slug used by Agent Engine tooling. # `agentengine create` should rewrite this when generating a new app from the template. name: my-agent # Python import path to the SDK App instance. # Format: <module path>:<variable name>. This template exposes `app` from # src/agent_my_agent/main.py. entrypoint: agent_my_agent.main:app framework: adk # Runtime feature flags controlled by agent.yaml, not .env. A key that is # present here wins over any ENABLE_* environment variable, so declaring memory # keeps ambient environment state from switching it on behind your back. # Set memory to true to enable long-term profile memory; VOYAGE_API_KEY must be # present in .env when memory is enabled. features: durable_workflow: true memory: false # Tool placement and pass-through secrets. This template's tools are all # remote-capable, so they run in the tool sandbox. sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: - get_current_date - save_user_info - recall_user_info version: 0.1.0 network: egress: - fqdn: openrouter.ai ports: [443] These settings do the following: - name: The name Agent Engine uses for your agent. It appears in your invoke URL and in agentengine workspace list. - features.memory: Turns the optional memory feature on or off. It's false because you answered no to the "Enable memory for local dev" prompt. - sandboxes.tool.tools: The tools the agent can call. - network.egress: The hosts the agent can contact. The CLI added openrouter.ai on port 443 because your model is served there. The system_message.py file in src/agent_my_agent holds the agent's instructions: SYSTEM_PROMPT = """ You are a daily inspiration assistant. Your name is Daily. If long-term memory is enabled, call `recall_user_info` at the start of a conversation to check what you know about the user. Address them by name and use any known details to personalize your responses. When long-term memory is enabled and the user shares personal details (name, location, interests, occupation, etc.), save each piece with `save_user_info` so you remember them in future conversations. When the user greets you or asks for inspiration, use the get_current_date tool to find out today's date, then craft a short, uplifting message of the day. Tailor the message to the season or any notable aspect of the date (e.g. start of a new month, a Friday, mid-year, etc.). Keep it warm, positive, and concise. """ The instructions are plain text that the model reads with every request. They give the agent its name, Daily, and say when to call a tool. This is why a prompt that asks for inspiration makes the agent call its get_current_date tool. The main.py file combines the instructions, the model, and the tools into one agent: @app.entrypoint def build_agent() -> LlmAgent: # ... return LlmAgent( name="daily", instruction=SYSTEM_PROMPT.strip(), model=app.llm(build_llm()), tools=app.tools(), ) The build_llm() function in llm.py sets the model you chose during agentengine create and reads your OpenRouter key from LLM_API_KEY. The daily here is the agent's name inside the code, which is separate from the name in agent.yaml. Finally, the tools.py file defines the tools. Each tool is a Python function with the @app.tool() decorator, which registers it so the model can call it. For example, the following is the get_current_date tool from the tools.py file: def register(app: App) -> None: @app.tool() def get_current_date(timezone_name: str = "UTC") -> str: """Return today's date in ISO 8601 format for an IANA timezone.""" try: timezone = ZoneInfo(timezone_name) except ZoneInfoNotFoundError: return json.dumps( { "error": f"Unknown timezone: {timezone_name}", "hint": "Use an IANA timezone like America/Los_Angeles.", } ) return datetime.now(timezone).date().isoformat() The model reads the function's docstring to determine when to call it. The template defines three tools: - get_current_date: Returns today's date for a timezone, UTC by default. - recall_user_info: Looks up what the agent has stored about you. - save_user_info: Stores a detail about you, such as your name. Run the Agent Locally Before you deploy your agent, run it on your machine. First, move into the agent directory: cd my-agent/agents/my-agent Then run every remaining agentengine command from the my-agent/agents/my-agent directory, because the CLI looks for agent.yaml in the current directory. Start the local stack To start the local stack, run: agentengine dev up > Note: Docker must be running before you run the preceding command. The stack is ready when the output returns ✓ Stack running, followed by its services and an example request: ✓ Stack running (hot-reload) oe http://localhost:55542 mongo mongodb://localhost:55544 ui http://localhost:3000 Invoke: curl -X POST 'http://localhost:3000/api/v1/projects/<project-id>/workspaces/my-agent/invoke' \ -H 'Content-Type: application/json' \ -d '{"message": "Hello"}' My first agentengine dev up run took several minutes because Docker had to download images and install Python dependencies. If yours takes a while, don't assume something has gone wrong. Subsequent runs reuse those dependencies and start much faster. The first run can also stop with the following error while the app is still installing its dependencies: Error: local app failed before becoming ready: Up About a minute (unhealthy) If you get the error, then leave the stack running and check its progress with the following command: agentengine dev status Until the install finishes, the status reports fewer than 4/4 running and ends with error="status unhealthy". Don't stop or restart the stack while you wait. Run agentengine dev status again every few minutes until the output looks like this: Stack: hot-reload app Up ... (healthy) oe Up ... (healthy) mongodb Up ... (healthy) ui Up ... 4/4 running Once all services report a healthy status, run agentengine dev up to get your invoke URL: ... ✓ Stack running (hot-reload) oe http://localhost:55542 mongo mongodb://localhost:55542 ui http://localhost:3000 egress agent sandbox allow_list (openrouter.ai:443); tool sandbox allow_list (openrouter.ai:443) HTTP(S)_PROXY agent sandbox: http://host.docker.internal:62445; tool sandbox: http://host.docker.internal:62446 only clients that honor HTTP_PROXY are blocked; native sockets are not Invoke: my-agent 'http://localhost:3000/api/v1/projects/eff47008585047156a391d7d/workspaces/my-agent/invoke' curl -X POST 'http://localhost:3000/api/v1/projects/eff470.../workspaces/my-agent/invoke' \ -H 'Content-Type: application/json' \ -d '{"message": "Hello"}' Next: Open VS Code and run "Dev Containers: Reopen in Container" for editing and debugging inside the running app container Restart: from this workspace dir, run agentengine dev restart Logs: agentengine dev logs Stop: agentengine dev stop Clean: agentengine dev clean ############################## # # # ui http://localhost:3000 # # # ############################## Four containers now run in Docker Desktop, under Containers, grouped as my-agent: - my-agent-ui: Serves the agent playground. - my-agent-oe-1: Runs the Orchestration Engine, which coordinates each request. - my-agent-app-1: Runs your agent code. - my-agent-mongodb-1: Stores data locally, so local development doesn't touch your Atlas cluster. Talk to your agent in the playground Open http://localhost:3000 in your browser, and send your agent this message: I am starting a new job tomorrow. Can I get some inspiration for my first day? The free model writes out its reasoning first, so expect a few paragraphs of planning before the reply. Invoke the agent from the command line You can also invoke the agent without using the browser. To do that, send the agent a request with curl. The request needs two values: - Invoke URL: Copy it from the Invoke: line of your agentengine dev up output. The URL contains your local project ID and your workspace name. > Note: A workspace is the unit Agent Engine runs, and locally it takes your application's name, my-agent. - User ID: Any name you choose to identify yourself to the agent, such as Oladele. I found that the example curl command generated by agentengine dev up omits user_id, which the Google ADK template requires. To avoid the resulting error, use the following command instead, with your own invoke URL: curl -X POST 'http://localhost:3000/api/v1/projects/<project-id>/workspaces/my-agent/invoke' \ -H 'Content-Type: application/json' \ -d '{"message": "I am starting a new job tomorrow. Can I get some inspiration for my first day?", "user_id": "Oladele"}' The response contains the agent's reply in its result field and reports "status": "completed". Stop the local stack To stop the containers, run the following command: agentengine dev stop Register the Project on Atlas Agent Engine Now that you've tested your agent locally, let's prepare it for deployment to Agent Engine. Locally, Docker supplied everything the agent needed. On Agent Engine, three things change. The agent needs a workspace to run in, its own copy of your secrets, and network access to your Atlas cluster. This section and the next two set these up in order. To register your agent, run: agentengine init Choose your Atlas organization, then the Atlas project that holds your M0 cluster. The CLI registers your agent as a workspace on Agent Engine. Upload Your Secrets to Atlas Agent Engine The deployed agent can't access your local .env file, so you must upload the following values as Agent Engine secrets: - MONGODB_URI: Your Atlas connection string. - LLM_API_KEY: Your OpenRouter API key. - VOYAGE_API_KEY: Your Voyage AI API key. Upload each one as a secret with the secret set command: agentengine secret set MONGODB_URI agentengine secret set LLM_API_KEY agentengine secret set VOYAGE_API_KEY Each command prompts for a value. A connection string looks like the following: mongodb+srv://<db_username>:<db_password>@<cluster-host>/?appName=devrel-tutorial-agentengine-deploy Replace the placeholders with your database user, its password, and your cluster host. Agent Engine stores these values as project secrets, so every workspace in your Atlas project can read them. Each secret set command confirms the upload. For example: ✓ Project secret VOYAGE_API_KEY set version: 3 updated_at: 2026-10-14T12:11:30Z Connect Atlas Agent Engine to Your Atlas Cluster Before you deploy your agent, you need to configure network access between Agent Engine and your MongoDB Atlas cluster. Without the required IP access entries, Agent Engine cannot connect to your cluster, and deployment may time out after waiting up to 30 minutes. You can configure your network access using the agentengine atlas setup command. The command's cluster list hides free M0 clusters, so you can't select yours there. It instead asks whether to keep the MONGODB_URI secret you uploaded in the previous section. The command also adds Agent Engine's IP ranges to the access list of your Atlas project. Run the command: agentengine atlas setup When prompted, enter y to keep the existing MONGODB_URI. The CLI then displays the IP address ranges that Agent Engine needs to access your cluster. Enter y again to add these ranges to your cluster's IP access list: Keep the existing MONGODB_URI for this Agent Engine project? [Y/n] y These CIDR ranges will be added so the platform can reach this cluster: - 44.214.209.237/32 - 52.44.27.64/32 Add these CIDR ranges to Atlas IP access? [Y/n] y ... Atlas integration is ready. The Atlas integration is ready output confirms that the network configuration is complete. Build and Deploy the Agent Your agent now has a workspace, its secrets, and a path to your cluster. Build and deploy it in one step: agentengine deploy --auto Without the --auto flag, you first run agentengine build to create the agent image, then agentengine deploy to deploy it. The --auto flag combines both steps into a single command and monitors the deployment until completion. Deployment takes several minutes. When it finishes, each component reports its status: ✓ Build succeeded ... ✓ Deployment succeeded version: v0.1.0 components: Orchestration Engine ready (2 replicas) Agent Sandbox ready (4 replicas) Tool Sandbox ready (4 replicas) url: https://agentengine.mongodb.com/project/<project-id>/deployments/<deployment-id> All three components reporting ready means that Agent Engine built your agent and started it. Agent Engine now runs the agent and its supporting services instead of your local Docker environment. Invoke the Deployed Agent Once your deployment succeeds, send your deployed agent a message: agentengine invoke "I have a big presentation today. Can you give me some motivation?" As in the playground, the free model writes out its reasoning before the reply. Now test whether the deployed agent remembers. Each invocation starts a new session unless you pass --session. A session holds the history of one conversation, while the optional memory feature stores facts about a user across conversations. Run these two commands in order, with the same session name: agentengine invoke --session tutorial-session "My name is Oladele." agentengine invoke --session tutorial-session "What is my name?" The output for the second command ends with the answer: Your name is Oladele. The second request doesn't contain your name, so the answer came from the session's history. Agent Engine stored that history in your Atlas cluster, and the deployed agent read it back. Clean Up Your Resources You've now deployed your agent, sent it a message, and tested its session history. If you no longer need the agent, follow these steps to remove the resources you created locally, on Agent Engine, and in Atlas. > Note: Other workspaces or applications in your Atlas project may use the project secrets, IP access entries, database user, or Voyage AI API key. Delete them only when nothing else uses them. First, stop and remove the local stack: agentengine dev stop agentengine dev clean Next, find your workspace ID: agentengine workspace list The list shows your workspace's ID next to its name: WORKSPACE ID NAME FRAMEWORK ws-xxxxxxxxxxxxxxxxxxxxxxxx my-agent adk Then delete the workspace: agentengine workspace delete <workspace-id> --yes You stored MONGODB_URI, LLM_API_KEY, and VOYAGE_API_KEY as Agent Engine secrets. To remove them, follow the instructions in Delete a Secret. Three resources remain in the Atlas UI: - The IP access entries: Go to SECURITY > Database & Network Access > IP Access List and delete your IP access entries. - The database user: Go to SECURITY > Database & Network Access > Database Users and delete the user you created for your connection string if you no longer need it. - The Voyage AI API key: Go to SERVICES > AI Model APIs > Model API Keys and delete the key if you no longer need it. Key Takeaways Here's what to take away from this tutorial: - Agent Engine is in public preview and only intended for evaluation and prototyping, with breaking changes expected. - agentengine create generates a project directory on your machine, and agentengine init registers it with Agent Engine. - A .env file serves local development only. Upload every value the deployed agent needs with agentengine secret set. - A deployed agent reaches your cluster from Agent Engine's network, so the cluster's IP access list must include Agent Engine's address ranges. - Agent Engine keeps each session's history in your Atlas cluster, so requests that share a --session value continue one conversation. Further Reading --- For more information on Agent Engine, see the following resources: - Get Started with the Atlas Agent Engine: MongoDB's reference guide for this workflow. - Install and Authenticate: Setup instructions for Windows and Linux. - Atlas Agent Engine examples: The repository holding this tutorial's template and the other starter templates. - Invoke an Agent: How to call your deployed agent from your own code. - Monitor: How to watch your deployed agent run.

The release note shows how to configure the MongoDB connection to enable automatic encryption. github.com/mongodb/laravel-mongodb/releases/tag/5… The documentation is being written, but it's not a lot more than the PHP driver's settings: php.net

Leveraging Skills in a MongoDB MCP Agent _This article was written by Jack Woehr._ _SoftWoehr LLC - Seiden Group - ProCern Technology Solutions._ --- Skills in a ReAct (Reason - Act) Agent for MongoDB In this article, we describe our open-source mymongodbmcpagent implementing a ReAct (Reason - Act) agent leveraging the MongoDB MCP Server and the MongoDB agent-skills package. Our code also provides a chat interface so that you can talk to your MongoDB instance and offer queries whose answers require strategies derived from the skills package, leading to multiple exchanges between the agent and the LLM. Evolving from a one-pass MongoDB Server Agent If you read my previous article, A Simple MongoDB Server Agent, you saw an agent/chat pair using an LLM provider to answer one-pass queries to MongoDB via the MongoDB MCP Server. I used that architecture to add MongoDB capabilities to a multi-agent dashboard that connects to many different projects I work on. Reuse the scripting from the earlier article Keep a link to that earlier article because its associated code on GitHub includes a nice script and .env.example to start the MongoDB MCP server, which can be used with the code we're presenting in this article. Prerequisite As in the earlier article, we assume you have a MongoDB Atlas Cluster with some sample data to query. Getting Started A full Getting Started document is available in the repository to help you set up. Add Skills to MCP - MCP tools are … tools! An LLM has no arms and legs. All it can do is talk, but once informed that there are tools (provided by the MCP server) and the skills to use them, it can call for the tools to be used based on its decisions. - Skills are instructions for using tools to accomplish tasks that require more than one tool call. They're in text, in Markdown format, and are prompts, plain English instructions for the language model to follow. Take a look at the skills directory of the repo just mentioned. - The Agent mediates between - the User - the Inference Engine (the LLM) - the tools and skills - loading the tools list for the LLM - loading the skills list for the LLM - calling the tools on behalf of the LLM Skills add complexity to the Agent Using skills requires the agent to execute a ReAct (Reasoning + Acting) loop that supports multiple LLM tool calls until it arrives at a response. The enhanced ReAct loop agent The code for the enhanced agent and its associated chat REPL is found at mymongodbmcpagent. Pay close attention to the .env.example file and create a .env file so that the agent and chat will both load and function as expected. The diagram below shows the flow of the agent. !Image description The payoff: more sophisticated queries In the screenshot below, with the agent (and, of course, the MongoDB MCP server) running, I have asked "find me pottery mugs". Answering this query requires that the LLM use its skills to exercise the ReAct loop to: - list the databases in the Atlas installation we've pointed it to - list collections in those databases looking for something useful ("Ha! There's a collection called pottery in the herwheel3_test database!") - work out how to find "mugs" in that collection ("Hmm, there are arrays of categories and tags in these documents …") As the Agent itself prints some of its processing to standard out, we can see that it took 6 iterations: [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Iteration 1... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Tool selected: list-databases [req=72b91571-d634-4597-a54a-6b992939335a] Session may have expired, attempting to reconnect... [req=72b91571-d634-4597-a54a-6b992939335a] ✓ Successfully initialized session with MongoDB MCP server [req=72b91571-d634-4597-a54a-6b992939335a] Reconnected, retrying tool call... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Iteration 2... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Tool selected: list-collections [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Iteration 3... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Tool selected: find [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Iteration 4... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Tool selected: collection-schema [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Iteration 5... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Tool selected: find [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Iteration 6... [req=72b91571-d634-4597-a54a-6b992939335a] [ReAct] Final answer reached. The secret sauce in the agent-server.js code The prompt reveals how the LLM interacts with the agent to make multiple tool calls and then signal when it has arrived at a final response: let currentPrompt = `You are an expert MongoDB autonomous agent. Your goal is to answer the user's question by taking actions and analyzing their results. Here is a list of available tools: ${formattedTools} ${loadedSkills ? `You have the following skills available to guide your actions:\n${loadedSkills}\n` : ''} User's request: "${question}" Decide what to do next based on the request. - If you need to use a tool to gather more information or execute a step, return a JSON object with "action": "tool", "toolName": "<name>", and "toolArguments": {<args>}. - If you have gathered enough information and can answer the user's request (or if no tools are needed), return a JSON object with "action": "answer", and "finalAnswer": "<your natural language answer>". Your response MUST be exactly ONE valid JSON object and nothing else. Do not use markdown blocks like \`\`\`json.`; You'll see in the source code that agent-server.js checks the incoming JSON on each pass through the LLM's responses, where it executes tool calls and watches for that finalAnswer indicator. Naturally, there is a configurable '.env ' limit to the number of iterations so you don't spend your rent money on a wedged inference. Agentic code assistance This project is extracted from a component of a larger project (my Dashboard, not yet released) and was coded over several months in spare time using the following agentic code assistants (listed in alphabetical order): - Cline - Gemini CLI - IBM Bob - Kilo - OpenCode - Zoo (formerly Roo) Variety may well be the spice of life, but it's also an essential oil for lubricating one's experience with agentic code assistance as this field rapidly evolves. Summary - MongoDB MCP server is not just a plugin to code assist; it's an application building block. - MongoDB MCP server is best leveraged using skills. - Skills require the agent to present a ReAct (Reasoning + Acting) architecture. - This article is accompanied by code. - The code supports several popular LLM providers. - The code is capable of servicing multiple concurrent requests.

Por dentro do MongoDB 9.0: o que muda no core do banco --- title: "Por dentro do MongoDB 9.0: o que muda no core do banco" published: true description: "Performance, Queryable Encryption, Intelligent Workload Management, Hibernate e o que eu testaria antes do upgrade, visto de dentro do MongoDB Champions Summit." tags: mongodb, database, nosql, java cover_image: dev-to-uploads.s3.us-east-2.amazonaws.com --- Fala pessoALL... O MongoDB 9.0 está disponível desde 28 de Setembro e foi apresentada oficialmente durante o MongoDB.local NYC em 30/09. Na minha opinião não é a versão de uma feature só: é a versão de um banco mais rápido com upgrade e, principalmente, mais previsível quando a carga foge do controle. Eu acompanhei a sessão de roadmap do core no MongoDB Champions Summit, dois dias antes do evento, e aqui mostro um o que muda de verdade, o que dá para usar hoje e o que eu vou testar antes de subir. Performance: mais banco pelo mesmo hardware Comparada com a 8.0, a MongoDB divulga para a 9.0 até 35% mais velocidade em findOne, até 30% em updateOne, até 2x de throughput em instâncias grandes e cerca de 20% a mais de throughput em cargas "transacionais". Na sessão, o time explicou que os dois primeiros números vêm de benchmarks de operações pontuais e o último de cargas com transações multi-documento, no estilo TPC-C e TPC-E. Parece ser só uma ou outra operação, mas as operações com "one" devem ser exploradas mais em nossas aplicações, na prática e volume do dia-a-dia isso faz bastante diferença. O ganho não veio de uma feature nova. Veio de três frentes: - Limpeza do motor de execução. Desde o ciclo da 8.0, performance virou meta da MongoDB como empresa. Times dedicados passaram meses revisando o caminho de execução de queries, até o nível de tickets de execução e implementações de mutex. - Otimização de compilação. Link-time optimization, profile-guided optimization (PGO) e reordenação de símbolos no build, para manter o código mais usado junto e quente no cache da CPU. - Escala vertical. Melhorias no software para aproveitar máquinas maiores. No Atlas, isso se soma ao hardware Gen2, esse ponto entra num próximo artigo especificamente sobre Atlas. Na prática, é ganho que chega com o upgrade, sem mudar uma linha da aplicação. Mas quero deixar claro que são números de laboratório, e a metodologia completa não foi publicada. Como sempre diz meu amigo Otávio Santana: o melhor benchmark é o seu! Antes de "cravar" qualquer porcentagem para o seu time, rode um com a sua carga. Segurança: busca por pedaço de texto em dados criptografados A novidade mais concreta de segurança é que o Queryable Encryption agora aceita consultas de prefixo, sufixo e substring, em GA. Até aqui, ele só fazia igualdade e range. Vale relembrar o conceito: o dado é criptografado no cliente, fica criptografado no banco e continua criptografado em memória durante a consulta. O servidor nunca vê o valor em claro. !Queryable Encryption: o valor e a busca saem cifrados do cliente e o servidor compara sem decriptar Isso destrava casos que antes forçavam a decriptar no app casos que fazem diferença não só na segurança mas também na experiência do usuário: autocomplete do nome de cliente, busca pelos primeiros ou últimos dígitos de um CPF, filtro por domínio de e-mail. Para quem lida com LGPD em fintech, saúde ou seguros, ou em qualquer outro segmento é a diferença entre criptografar o campo sensível ou deixá-lo de fora porque a tela de busca precisava dele. !Prefixo, Sufixo e Substring O que precisa ser decidido na criação da coleção, para cada campo: | Parâmetro | Para que serve | | --- | --- | | queryType | prefix, suffix ou substring (podem coexistir no mesmo campo) | | strMinQueryLength / strMaxQueryLength | Tamanho mínimo e máximo do trecho buscado. Em substring, o máximo vai de 2 a 6 e pesa muito na performance | | strMaxLength | Obrigatório em substring: tamanho máximo do valor armazenado, de 2 a 50 | | caseSensitive / diacriticSensitive | Se a busca diferencia maiúsculas e acentos. Precisa ser igual em todos os tipos de busca do campo | Os cuidados: cada campo consultável ganha um índice e aumenta o custo de escrita e de storage, regex continua sem suporte, e mudar o esquema de criptografia significa recriar a coleção. Quem testou o preview na 8.2 ou 8.3 deve contar com isso, porque a implementação GA não é compatível com a do preview. O mongocryptd foi depreciado: o caminho agora é a Automatic Encryption Shared Library (crypt_shared), sem processo separado. A outra frente é o "hardening" do próprio produto. Segundo o time de produto, a MongoDB participa em parceria de alguns projetos, usando modelos avançados para achar e corrigir vulnerabilidades antes que sejam exploradas. Para tornar a entrega previsível, as correções de segurança passam a sair no estilo Patch Tuesday, na segunda terça-feira do mês. A 9.0.2, publicada no mesmo dia do GA (28/09/2026), já corrige a CVE-2026-89099. Dica importante: não suba para 9.0.0, vá direto para o último patch. Pequenos ajustes que DBAs vão gostar: o log de auditoria ganhou o campo directRemote (direct_endpoint no schema OCSF), que registra o IP TCP real de quem abriu a conexão, separado do endereço informado via PROXY protocol por um load balancer. O campo também chegou às versões 8.0.33 e 8.3.9. Além disso, o novo parâmetro useInternalAuthzForX509 permite que clientes X.509 usem a autorização interna do MongoDB mesmo com autorização LDAP configurada. Resiliência: o cluster que não cai, se adapta Para mim, o Intelligent Workload Management (IWM) é a mudança mais importante da 9.0 para quem opera. A pergunta que o time fez na sessão resume o problema: quantos nós já foram acionados porque o banco estava lento, e não fora do ar? Num pico de Black Friday ou de ações, campanhas, chegam juntos o tráfego, os retries de conexão e aquela query sem índice. A pressão vai se acumulando, a latência dispara e alguém acaba resgatando o cluster na mão. Que como sabemos essa ação vem sempre acompanhada de alguns efeitos colaterais indesejáveis. O IWM transforma esse cenário num evento controlado. Ele não adiciona capacidade nem substitui o auto-scaling: ele ganha tempo até o auto-scaling ou um operador agir. Isso funciona em camadas, veja: 1. Fila na entrada. Um rate limiter por mongod admite operações num ritmo seguro e enfileira o excesso, em vez de deixar tudo competir por CPU. A fila é de controle de admissão: nada que está nela foi aceito ainda, então não há o que persistir. 2. Prioridade para o que é curto. A gente concorad que toda operação nasce "curta". Se ela cede (yield) vezes demais, é reclassificada como longa e vai para uma fila de menor prioridade. Leituras e escritas pontuais seguem, enquanto relatórios pesados, scans sem índice e tarefas internas desaceleram, mas continuam progredindo. 3. Proteção de recursos. Ajuste de cache e memória sob pressão, limitação de novas conexões em enchurradas de reconexão e bloqueio de escrita quando o disco está criticamente cheio (leituras continuam). 4. Load shedding, opcional. Em um estado de sobrecarga sustentada, a fila passa a ter limite e o excesso é rejeitado com um erro (sinalizando essa sobrecarga) retentável. Numa linha parecida como o Retryable Writes, lembra dele? !Sem IWM vs com IWM: fila na entrada, prioridade para operações curtas e load shedding As camadas 1 a 3 estão sempre ligadas em clusters dedicados do Atlas na 9.0, sem custo extra e sem mudar a aplicação. O load shedding é opt-in e exige ordem: primeiro atualize o driver, depois ligue o recurso. Os drivers compatíveis com backpressure entendem o erro de sobrecarga e fazem retry com backoff e jitter. Com um driver antigo, a aplicação recebe o erro sem saber tratá-lo. O Atlas disponibiliza um teste de load shedding que rejeita uma pequena porcentagem de operações de propósito, para validar o tratamento de erro. Utilize em dev ou staging para testar o comportamento das aplicações, mas nunca no cluster principal. | Proteção | M10/M20 | M30+ replica set | M30+ sharded | | --- | --- | --- | --- | | Fila na entrada e priorização | Não | Sim | Não (por enquanto) | | Cache/memória, conexões, bloqueio de escrita | Sim | Sim | Sim | | Load shedding (opt-in) | Não (por enquanto) | Sim | Não (por enquanto) | Perguntas que fizemos durante a sessão deixaram alguns pontos mais claros: - Não é configurável por requisição. Fila ou load shedding é uma escolha do cluster. Priorizar por workload ("esta operação assíncrona pode esperar, esta com cliente na tela não") está no backlog. - A fila é FIFO, por enquanto. O tamanho é limitado pelo número de conexões do cluster. As políticas rodam num policy engine separado do servidor, que pode evoluir mais rápido que as versões do banco. - Sobrecarga é medida por utilização de recursos, principalmente CPU, e pelo tempo de espera no controle de execução. - O auto-scaler ficou menos conservador. Um caso em que um index build travou as transações e o próprio auto-scaling. A boa notícias é que o algoritmo mudou para casos assim. - É só Atlas, por ora. Para Enterprise Advanced, a resposta foi "paridade eventual". Para acompanhar, o Atlas expõe as métricas Operation Rate Limiting e Connection Rate Limiting, alertas específicos de IWM e eventos no Activity Feed. Observabilidade e controle de queries No core, o avanço é o $queryStats passar a enxergar escritas. Agora insert, update e delete também geram estatísticas por query shape, ligadas por padrão via amostragem de 1% (internalQueryStatsSampleRate para leituras e internalQueryStatsWriteCmdSampleRate para escritas). A saída ganhou os blocos metrics.cursor, metrics.queryExec, metrics.queryPlanner e metrics.writes. Se você tem tooling que lê essa saída, revise antes do upgrade. O controle fino de queries também melhorou: - querySettings direto no comando. Você passa as configurações no próprio find, distinct ou aggregate, valendo só para aquela execução. Se o shape tiver configuração salva com setQuerySettings, a salva vence no mesmo campo. - maxTimeMS por query shape, definido com setQuerySettings. Útil para conter aquela query problemática sem deploy. - queryKnobs, para sobrescrever parâmetros internos do servidor em um único shape. Os dois últimos exigem FCV 9.0. Do lado do Atlas, o pilar de observabilidade da 9.0 inclui exportação nativa via OpenTelemetry (Prometheus, Grafana, Datadog, New Relic, sem camada de tradução), a nova Metrics UI e o Query Shape Insights cobrindo escritas. Produtividade: MongoDB agora fala Hibernate A MongoDB Extension for Hibernate ORM está em GA. É a mesma API de Session, as mesmas anotações @Entity e o mesmo HQL que o time Java já conhece, com o MongoDB embaixo. A extensão traduz a árvore de SQL do Hibernate para MQL: um join em HQL vira $lookup, um order by vira $sort. A própria Hibernate tentou algo parecido com o Hibernate OGM e descontinuou, por ser genérico demais. Nesta nova abordagem o escopo é só MongoDB. Desenhado especificamente para Java, mas abre o caminho para o reaproveitamento em drivers de outras linguagens, além de reaproveitamento do conceito e código para ferramentas de de migração como o Relational Migrator O que vem no GA: - HQL com os operadores mais usados (group by, in, between, agregações, caminhos aninhados). - Inner join e left outer join. Outros tipos de join estão no roadmap pós-GA. - Subdocumentos e arrays como mapeamento de primeira classe, sem achatar o modelo em tabelas. - Starter para Spring Boot, optimistic locking, índices, unique constraints e logging estruturado. - Native queries para o que o HQL não cobre, incluindo $search e $vectorSearch. Requisitos: Java 17+, Hibernate ORM 7.4, MongoDB 7.0 ou superior em replica set (o standalone não tem transações), licença Apache 2.0, artefato org.mongodb:mongodb-hibernate no Maven. Ainda sem cache de segundo nível, sem @DataJpaTest e sem validação em GraalVM native image. O próximo passo citado é expor Queryable Encryption e Vector Search pelo próprio Hibernate, além de uma extensão para Quarkus. Para quem faz migração de relacional, isso muda a conversa. O time de modernization da MongoDB já usa a extensão como dependência. Mas modelar documento continua sendo trabalho: reaproveitar as entidades de um esquema relacional sem repensar o modelo só troca o banco de lugar. Ciclo de vida: cinco anos para planejar Parece apenas mais um detalhe, mas é o que mais pesa em empresa grande: cada major version tem ciclo de vida de cinco anos, no Atlas e em Enterprise Advanced. Majors saem a cada dois anos. Entre elas, minors trimestrais chegam pelo auto-upgrade do Atlas e, desde a 8.2, também on-premises para casos específicos. Correções de segurança seguem o ritmo mensal citado acima. Na prática, quem fica na 9.0 tem uma janela real para planejar a próxima migração sem correr atrás de EOL todo ano. Quem quer as novidades primeiro usa o "Latest Version With Auto Upgrades" no Atlas, sabendo que, ao passar de major para minor, não dá para voltar para major até a próxima sair. A 9.0 também é a primeira major a incluir Search e Vector Search self-managed em Enterprise Advanced e Community, para quem quer busca sem um sistema à parte e sem Atlas. Esse é um assunto bastante pedido e pede um artigo detalhado sobre como implementar! Onde cada novidade está disponível A 9.0 é o mesmo motor em Atlas, Enterprise Advanced e Community, mas nem tudo que foi anunciado como "9.0" (por enquanto) roda fora do Atlas. | Novidade | Status | Atlas | Enterprise Advanced | Community | | --- | --- | --- | --- | --- | | Ganhos de performance do motor | GA | Sim | Sim | Sim | | Queryable Encryption: prefixo, sufixo, substring | GA | Sim | Sim | Sim, só com criptografia explícita (a automática não é Community) | | Intelligent Workload Management | GA | Sim, clusters dedicados | Paridade futura, sem data | Não | | Load shedding | GA, opt-in | M30+ replica set | Não | Não | | querySettings por comando, maxTimeMS por shape | GA | Sim | Sim | Sim | | Validação constraint | GA | Sim | Sim | Sim | | Extensão Hibernate ORM | GA | Sim | Sim | Sim (7.0+, replica set) | | OpenTelemetry nativo, nova Metrics UI | GA | Sim | Não | Não | | Ciclo de vida de 5 anos por major | Política | Sim | Sim | Não informado | O que eu vou testar antes de qualquer upgrade 1. Ir direto para o último patch. A 9.0.2 corrige a CVE-2026-89099 e a 9.0.4 corrige travamentos em step-up e resharding (SERVER-133518, SERVER-133988). 2. Limite de memória por operação. Cada operação agora tem teto de 1 GB ou 20% da memória do servidor, o que for maior. Agregações pesadas que rodavam na 8.x podem falhar com ExceededMemoryLimit. Rode as suas e acompanhe metrics.query.operationsFailedDueToMemoryLimit. 3. Limite de transações abertas. maxConcurrentMultiDocumentTransactions vem com 10.000. Acima disso, novas transações falham com TooManyOpenTransactions. 4. ODMs e syncIndexes(). Com FCV 9.0, o listIndexes passa a reportar collation: { locale: "simple" }, e Mongoose, Doctrine e Beanie podem dropar e recriar índices no startup (SERVER-89953). No Mongoose, as versões 9.10.4 e 8.24.5 resolvem. Nos demais, prefira createIndexes(). 5. Métricas renomeadas. metrics.changeStreams.showExpandedEvents virou metrics.changeStreams.option.showExpandedEvents, e houve mudanças em shardingStatistics. Atualize dashboards e alertas. 6. BSON inválido. Agora gera erro. Se algum integrador legado escreve BSON fora do padrão, você vai descobrir no upgrade. 7. Queryable Encryption em preview. Quem usou prefixo, sufixo ou substring no preview da 8.2/8.3 precisa recriar as coleções. 10. Load shedding. Driver deve ser atualizado primeiro, teste em staging, só depois ligar. Minha leitura Tem "quem" diga que a 9.0 parece mais uma 8.4 do que uma 9.0, porque não traz uma única feature que muda o jeito de rodar MongoDB. Eu entendo o argumento, mas acho que estão olhaando para o lugar errado. O que a 9.0 entrega (na minha visão) é previsibilidade: o mesmo hardware rendendo mais, o cluster que segura o pico em vez de capotar (salto importante), dado sensível que continua consultável e cinco anos de horizonte para planejar. Para quem opera o MongoDB no dia-a-dia, em produção e ambientes críticos, isso vale mais que um recurso de "simplesmente" apresentável e que gere aplausos durante o evento de lançamento. O que eu sugiro agora: subir um ambiente de teste no último patch, rodar as agregações mais pesadas contra o novo limite de memória e, se estiver no Atlas, atualizar os drivers para já ter o load shedding como opção. Se não estiver confiante em "fazer sozinho", conte comigo! No próximo artigo eu entro no Atlas: Atlas Infinite, hardware Gen2 e o que muda na conta. Se quiser ver isso ao vivo, vamos abrir as novidades no próximo MUG São Paulo data e local serão confirmados nos próximos dias. Fontes - Press release: MongoDB 9.0 e Atlas Infinite (29/09/2026) - Everything announced at MongoDB.local NYC 2026 (30/09/2026) - MongoDB 9.0 release notes - Intelligent Workload Management: documentação do Atlas - Blog: Intelligent Workload Management (08/10/2026) - Queryable Encryption: tipos de consulta e parâmetros - MongoDB Extension for Hibernate ORM (GitHub) - Política de versões do MongoDB - Percona: MongoDB 9.0, more 8.4 than 9.0? (09/10/2026) - Sessão "Novidades e Roadmap do MongoDB 9.0", MongoDB Champions Summit, Nova York, 28/09/2026 --- Leandro Domingues é Head de Databases e MongoDB Community Champion.