How to connect a Box MCP with Claude Code (4 steps)

Developers building automation or agentic workflows on top of Box have to navigate OAuth 2.0 app authorization, Box's folder-and-collaboration model, and token refresh before a single tool call returns a file.

To help your developers search files, manage folders, and retrieve shared content from the terminal with ease, we'll show you how to connect Box with Merge Agent Handler's Box MCP server.

How it works

Merge Agent Handler sits between Claude Code and the Box API.

You'd install the Merge CLI, authenticate once with your Merge Agent Handler account, and register the connection with a single command.

Once connected, Merge handles Box's OAuth credentials and token refresh on your behalf, so you never configure an app in the Box Developer Console or rotate access tokens across environments.

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude --version to confirm)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Box account with access to the files and folders you want to connect

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

Run the following to install the Merge CLI: pipx install merge-api

Then verify the installation: merge --version

2. Log in to Merge

Log in to connect the CLI to your Merge Agent Handler account: merge login

This authenticates your session and links the CLI to your Merge Agent Handler account.

Related: How to use a Box MCP in Codex

3. Add Agent Handler to Claude Code

Register the Agent Handler MCP server with Claude Code:

merge setup claude-code

4. Authenticate Box

Open a Claude Code session and run a query like:

List all files in my Box folder called "Vendor Contracts" that were modified in the last 30 days, including the file name, owner, and size.

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 Claude Code, we've addressed several more commonly-asked questions below.

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

With Box connected, Claude Code can:

• List and navigate folders: retrieve the contents of any folder in a connected Box account, including shared folders, without opening the Box web app

• Search files: run searches across Box to locate files by name, type, owner, or modification date

• Upload files: write files directly to a Box folder from the terminal, useful when an agent generates output that needs to land in a shared location

• Download and read files: retrieve file contents for processing, summarization, or use in downstream workflow steps

• Create and organize folders: scaffold folder structures programmatically when triggered by an event, such as a new client onboarding or project kickoff

• Generate shared links: create shareable URLs for specific files so agents can surface content to stakeholders without manual sharing steps

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

You can build a self-hosted MCP server on top of Box's API. For a developer working with a single Box account and a narrow use case, the initial setup is manageable: create an app in the Box Developer Console, choose an auth method, configure the OAuth redirect URI, obtain a refresh token, and write tool schemas for the endpoints you need.

The complexity compounds at team scale.

Box's access model runs on collaborations: a file or folder is visible to a user based on the collaboration roles attached to it, and those roles cascade through the folder tree in ways that depend on enterprise settings. A token that works for one user's view of the tree returns different results for another, and getting the scope wrong often returns partial results rather than a clear error.

Box also draws a hard line between standard OAuth apps and the enterprise-grade JWT and Client Credentials Grant flows that admin-level access requires. Picking the wrong app type means rebuilding the auth layer later when your use case grows beyond a single user.

Merge Agent Handler abstracts the auth layer and adds tool-level scoping on top. For example, an agent that reads documents can get the list and download tools and never reaches delete or collaboration-removal tools unless you explicitly grant them.

Every call is also logged with the timestamp, tool name, and inputs, giving teams an audit trail without any custom instrumentation.

Why connect Box to Claude Code?

Box holds the documents teams depend on: contracts, financial records, signed agreements, and shared deliverables.

Developers who need to build on that content currently retrieve it manually or write a dedicated Box API integration for each workflow that needs access.

With the Box MCP connected, Claude Code can search folders, retrieve files, and create or organize content without leaving the terminal.

This matters most when Box content feeds a downstream step: pulling the latest contract before generating a summary, checking whether a deliverable was uploaded before triggering a notification, or writing a generated report directly to a shared project folder.

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 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 AI 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 employee

• 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 Box MCP to retrieve documents, organize folders, and generate shared links, and more, while IT keeps centralized control over which folders each agent can reach.