How to connect a Box MCP to Cursor (4 steps)

You already write and reason about your code in Cursor.

But the moment you start building something that integrates with Box, you need details that only live in the API's responses.

How does Box's offset and marker pagination actually behave on a folder listing? What's the difference between the id, etag, and sequence_id fields on a file entry? What does a shared-link response return?

Without the MCP connection, answering those means leaving the editor, authenticating against Box's API separately, running test calls, and pasting responses back into the session where the integration code is being written.

To help your developers inspect Box's data model and query real files without leaving Cursor, we'll show you how to connect Box with Merge Agent Handler's Box MCP server.

How it works

Merge Agent Handler connects Cursor to the Box 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 .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach Box.

Once connected, Merge handles Box's OAuth token lifecycle so you never store credentials locally or rewire auth when tokens change.

Related: How to use the Box MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Box account with access to the folders you want to query

If you want to connect Merge Agent Handler's Box 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 your installation: merge --version

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account so it can make authorized requests to Box on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, safe to re-run if you need to reset.

Related: The steps for integrating a Box MCP with Codex

4. Authenticate Box

Open a Cursor chat in your project and try a prompt such as:

List the contents of the /Invoices folder and fetch one file's metadata so I can see the offset and marker pagination and the id, etag, and sequence_id fields before I write the sync loop.

The first time you invoke a Box tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

Box MCP FAQ

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

What can you do once the Box MCP is connected to Cursor?

With Box connected, Cursor can:

• Inspect the folder-listing response before writing a sync loop: fetch a real folder listing to see how the offset, limit, and total_count fields behave so the pagination loop you write terminates correctly

• Check file entry fields before writing change-detection code: pull a real file entry to see how id, etag, and sequence_id change across versions before you decide which to key your sync on

• Inspect a file's metadata shape before writing a parser: retrieve a real file's metadata so the deserialization code you write matches the fields the API actually returns

• Confirm the shared-link response structure before writing sharing code: fetch a real shared link to see the exact response shape before writing the code that creates or resolves links

• Distinguish file vs folder entries before writing traversal logic: pull a mixed folder listing to see the type discriminator on each entry so the branching in your traversal code is correct

• Inspect collaboration roles before writing access-control logic: fetch the collaborations on a folder so the permission checks you write reflect Box's actual role values rather than assumed ones

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

You can connect directly to Box's API using your own OAuth app. The API is documented, app creation is straightforward, and for a single developer building against one account the setup is fast.

The access control problem appears when you scale beyond one developer or one agent.

A Box token carries the access of the account that generated it, including every collaboration that account belongs to, so sharing it across agents or teammates means every agent operates with that same reach, with no way to restrict which operations a given agent can call. Rotating the token means updating every system that holds it at once.

Merge Agent Handler handles Box authentication centrally.

You define exactly which Box operations each agent can call: an agent that inspects file and folder structure for code generation can read that data without reaching write operations like uploading or deleting files. Every call is logged with the timestamp, tool, and inputs, so you have a full record of what each agent read or changed.

For teams running multiple agents against a shared Box account, that combination of scoped access and central logging is the difference between a controlled deployment and a shared credential problem.

Why connect Box to Cursor?

Box's API data, folder-listing responses, file entry fields, shared-link structures, isn't something you can accurately reconstruct from documentation alone.

These specifics are real-response details: the pagination has a particular offset-and-marker contract, file entries expose an id alongside etag and sequence_id versioning fields, and access is governed by collaboration roles that surface differently than a flat permission flag.

Connecting Box to Cursor puts that discovery step inside the editor.

Can I use Merge Agent Handler's Box MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Cursor to systems like Box.

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 confidential documents before results reach the editor session

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

The result is that employees can use the Box MCP to write sync loops against the real pagination contract, build parsers grounded in actual file metadata, write access-control code that reflects real collaboration roles, and more. All the while, IT keeps centralized control over which folders each agent can reach.