Connect an AI agent to Box

An AI agent is more useful when it can work with the same current content as your team. This tutorial explains how to connect an agent to an isolated Box developer account through either the Box CLI or the hosted Box MCP server.

The examples use Codex, but the connection patterns apply to other agents. Use the Box CLI path when an agent can run shell commands. Use the Box MCP path when an agent supports the Model Context Protocol.

What you are building

By the end of this tutorial, your agent can read, search, upload, organize, and use Box AI with Box content.

Box CLI path

Box MCP path

Connect the hosted Box MCP server with OAuth. The Box user you authorize determines the content available to the agent.

Authentication and access boundaries

Both paths in this tutorial use OAuth. The agent acts as the Box user who completes the OAuth flow and can access the content available to that user, subject to the integration’s scopes and Box security policies. The Box CLI’s built-in OAuth application supports files and folders, Box AI, and Box Sign. Box MCP uses the scopes configured for the integration. Neither path restricts the agent to a single folder when you authorize your own user.

Use a fresh Box developer account that contains only sample content. Do not use this tutorial to connect an agent to a production Box enterprise, your everyday Box account, or sensitive content.

Choose the right path

Both paths use the same developer-account user but expose Box through different interfaces.

	Box CLI	Box MCP
Interface	Shell commands	MCP tools
OAuth login	`box login` locally or `box login --code` on a headless runtime	Browser authorization through the MCP client
Content access	Content available to the signed-in Box user	Content available to the signed-in Box user
Recommended use	Agents that can run terminal commands	MCP-native agents and chat clients

Choose the Box CLI path if your agent runs in a terminal or on a server, or inside a container. Choose the Box MCP path if your agent is MCP-native.

Prerequisites

An isolated Box developer account

Create a free Box developer account specifically for testing. Add only sample content that you are comfortable making available to the agent. The account works for both paths and gives you the admin access needed to enable the MCP integration yourself.

Your agent, installed and working

Use any coding or autonomous agent. Confirm it runs and responds before you connect Box.

Example: installing Codex

# via npm
npm install -g @openai/codex

# or via Homebrew
brew install codex

codex --version

Swap these for your own agent’s install steps. Claude Code, Cursor, Hermes, Pi, and OpenClaw each have their own.

Basic terminal familiarity

You’ll run a handful of commands. For a remote login, you also need access to a browser on another computer.

Set up the connection

Box CLI (OAuth)
Box MCP (hosted server)

The Box CLI turns Box into a headless, scriptable surface. Any agent that can run shell commands can then read, upload, search, and organize Box content by calling a box command.The CLI can also call Box AI. The box ai:ask, box ai:text-gen, and box ai:extract commands send requests to the Box AI API for content stored in Box.

A free developer account includes 1,000 AI Units each month for testing Box AI capabilities. Higher-tier Enterprise plans offer increased AI query limits and advanced capabilities. Enable the AI API for your account before using these commands.

You’ll authenticate the CLI with OAuth as your developer-account user. The correct login command depends on whether a browser is available on the machine where the agent and CLI run.

Install the Box CLI

Install the CLI on the machine where the agent runs:

npm install --global @box/cli
box --version

Choose the instructions that match where the Box CLI and agent run.

Local computer with a browser

Run the standard login command on the same computer as the agent:

box login

At the authentication-method prompt, choose the official Box CLI application. The CLI opens your browser and starts a local callback server. Sign in with your isolated developer-account user and select Grant Access to Box. The browser returns the authorization response directly to the CLI.

VPS, remote host, or headless container

Start a manual-code login on the remote runtime:

box login --code

The runtime does not need a browser, but a person must still complete the OAuth authorization in a browser on another computer.At the authentication-method prompt, choose the official Box CLI application. The CLI prints an authorization URL and waits for input:

Copy the URL and open it in a browser on your local computer.
Sign in with your isolated developer-account user and select Grant Access to Box.
The browser redirects to a localhost URL that contains code and state query parameters. The page fails to load because the callback server is not running on your local computer. This is expected.
Copy the code and state values from the browser’s address bar and enter them in the remote CLI when prompted.

For the complete flow, see Login for headless environments.

In a container, persist the CLI’s authentication state in a protected volume so it survives restarts. Never bake tokens or CLI authentication data into a container image or commit them to source control. If the stored OAuth session is removed or can no longer be refreshed, run box login --code again.

Verify the Box user

Confirm that the active CLI session uses your developer-account user:

box users:get me

The response should show the name and login of the Box user that completed OAuth. This is the identity your agent uses for every Box CLI command.

Connect the agent and inspect access

Add instructions for your agent. In Codex, add them to AGENTS.md in the working directory:

## Box access
- Use the Box CLI for Box operations.
- Use the currently authenticated OAuth session. Do not add or switch credentials.
- Operate only on Box items explicitly named in the task.
- Ask before deleting, moving, or overwriting content.

Then enter this prompt in the agent chat to confirm the identity and content available to it:

Use the Box CLI to show the authenticated Box user, then list the items at
the root level.

The agent should identify your developer-account user and list the sample content in the account. In the background, it executes these CLI commands:

box users:get me
box folders:items 0

Put it to work

Enter each prompt in the agent chat in order; each builds on the last:

Create a short product-launch brief and a separate notes file in the
root of my Box account.

Read the product-launch brief and notes in the root of my Box account,
draft a one-page status summary, and save it at the root.

Troubleshoot the CLI path

No browser opens on the runtime: use box login --code and complete authorization in a browser on another computer.
The localhost redirect fails during --code login: this is expected. Copy the code and state values from the URL into the CLI.
The CLI shows the wrong user: start a new login and authorize with the isolated developer-account user.
The OAuth session is no longer valid: run the appropriate box login command again.
Box AI permission error: confirm that the AI API is enabled for your developer account.

The Model Context Protocol allows an agent to use Box tools for search, Box AI, and file and folder operations. Box hosts the server at https://mcp.box.com.The Box user who completes OAuth determines what the agent can access. For this tutorial, sign in with the user from your isolated developer account.

Any MCP client can connect to Box through https://mcp.box.com and OAuth. This example uses the Box plugin for Codex. See the Box MCP platform setup guides for other clients.

Enable the integration

AdminYou are the admin of your free developer account, so you can complete this step yourself:

Sign in to the Box Admin Console.
Select Integrations in the left navigation, then search for ChatGPT and set its availability to the users who need it. For a different MCP client, enable that client’s integration instead.
Select Box AI in the left navigation, then open Settings. Enable AI API and Official Box Integrations for the required users or for all users.

Confirm the Box user for OAuth

Use the user from your isolated developer account. The agent can access the content available to this user, so confirm that the account contains only sample content before continuing.

Install the Box plugin

Open the Codex app or start a Codex CLI chat. In the chat input, enter:

/plugins

Open the plugin marketplace, search for Box, and install the plugin. Complete the OAuth flow with the Box user selected in the previous step.

Using a different agent? You can connect to the same server (https://mcp.box.com) elsewhere: in Claude, add Box under Connectors; in Cursor, add it as a remote MCP server; other platforms follow their own “add MCP server” flow and then the same OAuth sign-in.

Confirm the MCP server

In the same agent chat, enter:

/mcp

Confirm that the Box server is connected and that its tools are available.

You should see the Box server connected, exposing tools such as search_files_keyword, ai_qa_single_file, upload_file, and list_folder_content_by_folder_id.

Confirm the agent's access and run a task

In the agent chat, enter:

Use the Box tools to identify the authenticated Box user and list the items
at the root level. Report the user name and each folder name.

The agent should identify your developer-account user and list the sample content available to that user.Then enter these prompts in the agent chat:

Create a short product-launch brief and a separate notes file in the
root of my Box account.

Read the product-launch brief and notes in the root of my Box account,
draft a one-page status summary, and save it at the root.

Troubleshoot the MCP path

The integration is unavailable: verify the integration and Box AI settings in the Admin Console.
The agent has broader access than expected: disconnect and reconnect with the intended Box user.
Restrict available tools: configure the MCP client to allow only the tools the agent needs. In Codex, configure this in ~/.codex/config.toml.

Plan a production agent identity

This tutorial uses user OAuth in an isolated developer account so that you can evaluate the connection without creating a server-authentication app. Do not copy this authentication design into a production workflow without reviewing the identity, scopes, credentials, and content boundary with your Box Admin and security team. The Box user types relevant to an agent integration are:

User type	Interactive login	How it is created	Production considerations
Managed User	Yes	Provisioned in a Box enterprise	Can complete OAuth for the CLI or MCP. The agent receives the content access of that user and the user consumes a Box seat.
Service Account	No; API only	Generated when an Admin authorizes a CCG or JWT app	Represents the server app. Its capabilities depend on app scopes and access settings, and it can perform Admin-level actions when elevated permissions are enabled.
App User	No; API only	Created through the API by an authorized app’s Service Account	Provides a separate folder tree and identity for a process, agent, or tenant. It cannot sign in to Box or complete MCP OAuth.

For a production agent, an organization may choose to have its Admin or platform team authorize a server app and provision an App User for the agent. An App User does not remove the Service Account or the parent CCG or JWT application from the architecture. The Service Account creates the App User, and the authorized application obtains tokens for it.

Do not give a shell-capable agent direct access to the parent application’s client secret, private key, or unrestricted Service Account credentials. Keep parent credentials under platform-team control, request only the minimum scopes, keep the application at App Access Only unless broader access is required, and expose narrowly scoped operations or short-lived tokens to the agent through an organization-approved runtime.

CCG and JWT apps always require explicit Admin authorization in a managed enterprise because their Service Accounts can receive elevated permissions. App User provisioning, credential brokering, monitoring, and revocation are production architecture concerns and are outside this tutorial. To design that flow, see Box user types, create an App User, select an authentication method, and Platform App approval.

Use cases

Content and launch work: create captions, descriptions, and review notes from the current project files.
Living documents: assemble a release checklist from the current specification, mockups, and quality-assurance notes.
Engineering context: give an agent access to current design documents, incident notes, and other maintained technical content.
Legal and contracts: compare the current redline with a previous version and flag changed clauses for human review.

Box CLI docs

Command reference and authentication options.

Headless CLI login

Complete OAuth when the CLI runs on a VPS or in a container.

Box MCP server

Hosted server, supported platforms, and available tools.

Box user types

Compare Managed Users, Service Accounts, and App Users.

​What you are building

Box CLI path

Box MCP path

​Authentication and access boundaries

​Choose the right path

​Prerequisites

​Set up the connection

​Plan a production agent identity

​Use cases

​Related resources

Box CLI docs

Headless CLI login

Box MCP server

Box user types

What you are building

Authentication and access boundaries

Choose the right path

Prerequisites

Set up the connection

Plan a production agent identity

Use cases

Related resources