> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB Atlas Agent Engine

> Give an agent on MongoDB Atlas Agent Engine live web data from Nimble, with the starter agent's SDK tools or Nimble's hosted MCP server.

Give an agent on [MongoDB Atlas Agent Engine](https://www.mongodb.com/docs/agentengine/), MongoDB's platform to build, deploy, and govern agents, live web data from Nimble. The [starter agent](https://github.com/Nimbleway/nimble-agent-engine-starter) searches the web, reads pages, and runs multi-step research, then cites its sources.

> [!NOTE]
>
> Atlas Agent Engine is in public preview and may change. MongoDB does not recommend production workloads on it during the preview.

## Quick Start

You need Docker running, the `agentengine` CLI signed in, and a Nimble and an OpenAI API key. See [Prerequisites](#prerequisites).

```bash theme={"system"}
git clone https://github.com/Nimbleway/nimble-agent-engine-starter.git
cd nimble-agent-engine-starter
cp env.example .env   # set NIMBLE_API_KEY, and LLM_API_KEY to your OpenAI key
agentengine dev up
```

Open the playground at `http://localhost:3000` and try:

* "What are the latest announcements about MongoDB Atlas?"
* "Summarize [https://www.mongodb.com/docs/agentengine/](https://www.mongodb.com/docs/agentengine/)"
* "Research the top three open-source vector databases and compare their licenses."

`MONGODB_URI` in `.env` can stay empty: local runs use their own MongoDB. To use your Atlas cluster in local dev instead, set `mongodb.local: false` in `dev.yaml` and fill in `MONGODB_URI`. Stop it with `agentengine dev down`.

## Prerequisites

* A Nimble API key. [Sign up](https://online.nimbleway.com/signup) for a free trial.
* The [`agentengine` CLI](https://www.mongodb.com/docs/agentengine/build/install-authenticate/), installed and signed in.
* Docker, running.
* An OpenAI API key. To use another model provider, see [Change the model provider](#change-the-model-provider).

## Two ways to add Nimble

The starter agent supports both, with the same Nimble API key. The default path defines the tools in `src/hello_world_agent/tools.py` with the [Nimble Python SDK](https://docs.nimbleway.com/nimble-sdk/sdks/python.md). The other path serves search and extract from the [Nimble MCP server](https://docs.nimbleway.com/integrations/mcp-server/mcp-server.md), set up in `agent.yaml`.

| Tool | What it does | SDK tools | Hosted MCP |
| - | - | - | - |
| `nimble_search` | Searches the live web. Returns titles, URLs, and snippets. | Yes | Yes |
| `nimble_extract` | Reads one page and returns it as markdown. | Yes | Yes |
| `nimble_research` | Runs a Nimble [Agent](https://docs.nimbleway.com/nimble-sdk/web-search-agents/overview.md) on a question and returns a cited answer. | Yes | No (SDK tool only) |

### How it works

**1. Tools reach only allowed hosts**

Nimble tools can call out only to hosts on the `egress` list (the outbound allow-list) in `agent.yaml`. The starter allows `sdk.nimbleway.com`. Your `NIMBLE_API_KEY` is passed in as a secret.

**2. Long research continues across calls**

By default, Agent Engine gives each tool call 30 seconds. A Nimble Agent run can take longer, so `nimble_research` waits about 20 seconds, then returns `status: running` with a `run_id` and `agent_id`. The model calls the tool again with both until the cited answer is ready.

`nimble_research` defaults to `low` [effort](https://docs.nimbleway.com/nimble-sdk/web-search-agents/efforts.md), and the model can request a higher effort per call. Higher efforts cost more per run and take longer (`x-high` can run 15 to 30 minutes, which means many polling calls). To cap cost, remove the `effort` argument or limit its values in `tools.py`.

## Use the hosted MCP server

To use Nimble's hosted MCP server for search and extract:

**1. Add the MCP server to agent.yaml**

The starter's `agent.yaml` ships this block commented out. Uncomment it:

```yaml agent.yaml theme={"system"}
mcp:
  servers:
    nimble:
      transport: streamable_http
      url: https://mcp.nimbleway.com/mcp
      headers:
        X-Client-Source: mongodb-atlas-agent-engine
      auth:
        type: bearer_env
        token_env: NIMBLE_API_KEY
      allowed_tools: [nimble_search, nimble_extract]
      timeout_seconds: 60
```

Keep `allowed_tools` set. Without it, the model also sees MCP tools that start paid crawls or delete Nimble Agents.

**2. Allow the MCP host**

Uncomment the `mcp.nimbleway.com` entry under `egress` in `agent.yaml`, so the sandbox can reach the server.

**3. Remove the duplicate SDK tools**

Delete `nimble_search` and `nimble_extract` from `tools.py` and from `sandboxes.tool.tools` in `agent.yaml`. Otherwise the model sees each tool twice.

## Deploy

Deploying needs the **Project Owner** role and an Atlas cluster. `agentengine atlas setup` connects the cluster, adds Agent Engine to the cluster's IP access list, and stores its `MONGODB_URI` as a secret. See MongoDB's [Set Up Atlas Resources](https://www.mongodb.com/docs/agentengine/deploy/atlas-setup/) guide.

```bash theme={"system"}
agentengine init
agentengine atlas setup
agentengine secret set LLM_API_KEY --workspace-scope
agentengine secret set NIMBLE_API_KEY --workspace-scope
agentengine build
agentengine deploy
```

## Change the model provider

The starter uses OpenAI. To switch, change the client in `src/hello_world_agent/llm.py`. Then replace `api.openai.com` in the `egress` list of `agent.yaml` with your provider's host.

## Good to know

* **Use a dedicated Nimble API key** for the agent, so you can [track its usage](https://docs.nimbleway.com/nimble-sdk/admin/account-management.md#track-usage-by-api-key) separately. Nimble billing is separate from MongoDB billing. See [pricing](https://docs.nimbleway.com/nimble-sdk/admin/pricing.md).
* **Scope `agent_name` per user.** `nimble_research` accepts an `agent_name` parameter. All callers that share the same API key and name share that agent's memory, so in a multi-user deployment, scope the name per user to avoid leaking context between them.
* **Nimble maintains the starter.** For bugs in the starter, open an issue on its [GitHub repository](https://github.com/Nimbleway/nimble-agent-engine-starter/issues). For your Nimble account or API, [contact Nimble support](https://nimbleway.com/contact-general/).

## Resources

> [card] [Starter agent](https://github.com/Nimbleway/nimble-agent-engine-starter)
>
> The full agent: tools, `agent.yaml`, and the MCP alternative.

> [card] [Nimble MCP Server](https://docs.nimbleway.com/integrations/mcp-server/mcp-server.md)
>
> Tools, authentication, and setup for other MCP clients.

> [card] [Agent](https://docs.nimbleway.com/nimble-sdk/web-search-agents/overview.md)
>
> How Nimble Agents run research and return cited answers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.