How to connect a Dropbox MCP with Codex (4 steps)

When you hand Codex a task to build a file-processing job or a Dropbox sync, you usually describe the files in the prompt.

That description rarely matches what's actually in the account.

The real folder structure, the columns in the CSV, and the way shared and team folders nest are details a summary skips. This leads Codex to generate a parser for an assumed file shape, path logic that breaks on the real hierarchy, or a sync that ignores shared folders entirely.

To give Codex direct access to Dropbox as it works through your coding tasks, we'll show you how to connect Dropbox with Merge Agent Handler's Dropbox MCP server.

How it works

Merge Agent Handler connects Codex to the Dropbox API through the Merge CLI. You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a Merge CLI section to your project's AGENTS.md file, which tells Codex when to call merge search-tools and merge execute-tool to reach Dropbox.

Once connected, Merge handles OAuth token storage and refresh on your behalf, so you never embed Dropbox credentials in your repo or manage per-user authorization state yourself.

Related: How to use the Dropbox MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Codex access (available via the OpenAI platform)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Dropbox account with access to the folders your tasks need

If you want to connect Merge Agent Handler's Dropbox MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install the Merge CLI with pipx: pipx install merge-api

Verify the install: merge --version

2. Log in to Merge

Run the following to authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your Merge account and stores your session credentials locally.

3. Add Agent Handler to Codex

From the root of the project where you want Codex to reach Dropbox, run:

merge setup agents-md

This writes a Merge CLI section to your project's AGENTS.md file so Codex knows to use the CLI when a task needs Dropbox data. The command is idempotent, safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so the configuration travels with the repo.

Related: The steps for integrating a Dropbox MCP with Cursor

4. Authenticate Dropbox

Create a Codex task that needs live Dropbox data. For example: "Read the CSV files in the /exports folder, then scaffold a job that parses them into our internal schema and flags malformed rows."

The first time Codex invokes a Dropbox tool, a Magic Link will appear to complete connector authentication.

Once authenticated, Codex can reach your Dropbox account through Merge for every later task in this project.

{{this-blog-only-cta}}

Dropbox MCP FAQ

In case you have more questions on setting up and using the Dropbox MCP with Codex, we've addressed several more commonly-asked questions below.

What can you do once the Dropbox MCP is connected to Codex?

With Dropbox connected, Codex can:

• Read a real data file before scaffolding a parser: pull an actual CSV or JSON file so the parsing code it generates matches the real columns, delimiters, and encoding rather than an assumed layout

• Pull a folder structure before generating path or sync logic: fetch the real hierarchy, including shared and team folders, so the traversal and path-handling code it writes matches how the account is actually organized

• Read a spec or requirements file before scaffolding a feature: retrieve a document stored in Dropbox so the code it generates follows the requirements in the source rather than a paraphrase of them

• Pull file metadata before generating test fixtures for a processing job: fetch real file names, sizes, and modification dates so the fixtures and assertions it produces reflect what the job will actually encounter

• Read multiple files before generating batch-processing code: fetch a set of files so the batching and error-handling code it writes accounts for the real variation across them

Why use Merge Agent Handler vs. a self-hosted Dropbox MCP server?

You can build your own MCP server on top of the Dropbox API. For one developer on one account, it's workable: create an app, run the OAuth flow, and write tool schemas for the endpoints your tasks touch.

It gets harder once more than one person uses it or tasks run in CI.

Dropbox issues short-lived access tokens with refresh tokens, and every connected user needs their own token pair, refresh cycle, and handling for revoked access. A silent refresh failure means a Codex task quietly runs against stale or missing files, with no central view of which connections are live.

A self-hosted server doesn't change that. You still own the OAuth plumbing and the app, and now you maintain the server too. Community Dropbox MCP builds vary in endpoint coverage and upkeep, so you're betting on someone else's maintenance.

Merge Agent Handler handles credential storage and token refresh across every connected user. You can scope exactly which Dropbox operations a Codex task can call, and every call is logged with identity, timestamp, and inputs.

For an agent reading files that can contain sensitive documents, scoped access plus full audit logging is the foundation you want in place first.

Why connect Dropbox to Codex?

Dropbox holds the data files, folder structures, and documents that file-handling code has to match exactly.

Codex tasks that build parsers, sync jobs, or batch-processing pipelines need that ground truth to produce code that works against the real account.

The alternative is describing the files in the prompt, and those descriptions are always incomplete. A guessed column layout, an omitted shared folder, or an assumed file format is enough to make Codex generate code that fails on the first real file.

Connecting Dropbox lets Codex read the actual files when a task needs them. The real CSV before a parser, the real hierarchy before path logic, the real spec before a feature: Codex works from the account itself, not a paraphrase of it.

Can I use Merge's Dropbox MCP with my employees?

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI tools like Codex to systems like Dropbox.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which folders an employee's agent can reach by role or team

• DLP and policy enforcement on tool calls, so admins can block retrieval of sensitive documents before results reach a Codex task's context

• User-level audit logging so security and IT teams can review which files and folders were accessed, by which employee identity, and when

Taken together, employees can use the Dropbox MCP to scaffold parsers against real data files, generate sync jobs that handle the real folder structure, build batch pipelines grounded in actual file metadata, and more. All the while, IT keeps centralized control over which folders each agent can reach.