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 Box 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 build

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

Box CLI path

Connect a Client Credentials Grant service account. The agent has its own Box identity and can access only the folders shared with it.

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

The authentication method determines which Box identity the agent uses and what content it can access:

Personal OAuth: the agent acts as the Box user who completes OAuth. It has the same access as that user.
Client Credentials Grant: the agent acts as a separate service account. The service account starts without access to your content and can access only the folders shared with it.
Dedicated managed user: the agent completes OAuth as a user created for the agent. Its access is limited to the folders shared with that user. This option requires an available seat on a paid plan.

On a free developer account, the MCP connection uses your own account because the account has one seat. Use the Box CLI service-account path when you need a separate identity with access limited to a project folder.

Choose the right path

Both paths connect an agent to Box, but they use different identities and access boundaries.

	Plain OAuth	Box CLI	Box MCP
Who the agent acts as	The user who authorizes the app	A dedicated service account	The Box user who completes OAuth, which is you on a free developer account
Interactive login	Required	Not required	Required once
Folder scoping	Uses the authorizing user’s access	Share specific folders with the service account	Use a dedicated user with access to specific folders
Recommended use	Short-lived local testing	Terminal agents and headless automation	MCP-native agents and chat clients

On a free developer account, the MCP connection uses your own account because the account has one seat. The agent can access the content you can access. Use the Box CLI path when you need a separate service identity and a strict folder boundary on a free developer account.

Choose the Box CLI path if your agent runs in a terminal or on a server, or if you need to scope it to a shared project folder. Choose the Box MCP path if your agent is MCP-native and you are comfortable authorizing the appropriate Box user through OAuth.

Prerequisites

A Box account you can build on

A free Box developer account is all you need. It works for both paths and comes with admin access, so you can enable the MCP integration and authorize apps yourself without waiting on a separate enterprise admin.

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 and edit one or two small config files.

Set up the connection

Box CLI (service account)
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 as a CCG service account so the agent gets its own Box identity and only sees folders you explicitly share with it.

Install the Box CLI

Install the CLI on the machine where the agent runs:

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

Create a Server app in the Developer Console

Go to the Box Developer Console and click New App. In the dialog:

Enter an App Name (for example, agent-service).
Under App Type, choose Server. If the option displays, select Client Credentials Grant.
Click Create.

Authorize the app and copy its credentials

Authorize the app in the Developer Console. For enterprise accounts, follow the platform app approval guide or ask an administrator to approve the app.In the app’s App Details sidebar, copy the following values:

Properties: Enterprise ID
Access: Client ID and Client Secret

Store the credentials securely

Keep credentials outside the agent’s working directory and outside source control. The JSON file below is only a temporary bootstrap file. Create a restricted directory for it:

mkdir -p ~/.box-agent
chmod 700 ~/.box-agent

Create ~/.box-agent/ccg-config.json:

{
  "boxAppSettings": {
    "clientID": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  },
  "enterpriseID": "YOUR_ENTERPRISE_ID"
}

Restrict the file to your user, then import it into the Box CLI:

chmod 600 ~/.box-agent/ccg-config.json
box configure:environments:add ~/.box-agent/ccg-config.json --ccg-auth --name service --set-as-current
rm ~/.box-agent/ccg-config.json

The CLI stores the imported environment in your operating system’s secure credential storage, such as macOS Keychain or Windows Credential Manager. On a shared host, in CI, or in production, retrieve the bootstrap values from a secret manager at runtime and remove the temporary file immediately.

Verify the service account

Confirm that the active CLI environment uses the service account:

box users:get

You should see an automation / app user, not your personal account. This non-human identity is who your agent acts as in Box.

Name: agent-service
Login: AutomationUser_..._....@boxdevedition.com

Share one project folder

Create a project folder in the Box web app, such as Agent Workspace. In the Developer Console, copy the service account email address from App Details. In the Box web app, open the project folder, select Share, and invite that address with the Editor role.The service account can access only folders shared with it.

Connect the agent and verify 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 active "service" environment only. Do not add or switch credentials.
- Operate only in folders shared with the service account.
- Ask before deleting or overwriting content.

Then enter this prompt in the agent chat to prove the boundary holds:

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

The agent should identify the automation user and list only the folders shared with that identity. In the background, it executes these CLI commands:

box users:get
box folders:items 0

Put it to work

In the Box web app, open the project folder and note its numeric folder ID from the URL. For example, the URL might look like this:

https://app.box.com/folder/1234567890

The folder ID is the number 1234567890 after folder/. Then enter each prompt in the agent chat in order; each builds on the last. If the agent struggles to find the Agent Workspace folder, give it the folder ID noted above:

Create a short product-launch brief and a separate notes file in the
Agent Workspace folder.

Read the brief and notes in the Agent Workspace folder, draft a one-page
status summary, and save it in the same folder.

Troubleshoot the CLI path

The CLI shows your personal account: activate the service environment with box configure:environments:set-current service.
Authorization error: confirm that the app is approved for the enterprise.
The agent sees no files: confirm that the service account is a collaborator on the project folder.
Box AI permission error: confirm that the AI API is enabled and that the service account can access the target folder.

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. On a free developer account, sign in as yourself. On a paid plan with an available seat, you can create a dedicated managed user and give that user access only to the project folder.

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

Admin

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.

Choose the Box user for OAuth

On a free developer account, use your own Box user. The agent has the same access as your account, so use this option only when that access level is appropriate.On a paid plan, create a dedicated managed user, such as agent@acme.com. Create a project folder, such as Agent Workspace, and share that folder with the managed user using the Editor role. The agent then accesses the content available to that managed user.

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. If you have a dedicated user, always authorize as that user, not yourself. That’s what keeps the agent scoped.

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.

With a dedicated managed user, the agent should list only the folders shared with that user. With a free developer account, it can list the content that your user can access.Then enter these prompts in the agent chat:

Create a short product-launch brief and a separate notes file in the
Agent Workspace folder.

Read the brief and notes in the Agent Workspace folder, draft a one-page
status summary, and save it in the same folder.

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.

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.

Box MCP server

Hosted server, supported platforms, and available tools.

Client Credentials Grant

Details about service-account authentication for the CLI path.

Box AI with the CLI

Use Box AI commands for Q&A and summaries.

​What you build

Box CLI path

Box MCP path

​Authentication and access boundaries

​Choose the right path

​Prerequisites

​Set up the connection

​Use cases

​Related resources

Box CLI docs

Box MCP server

Client Credentials Grant

Box AI with the CLI

What you build

Authentication and access boundaries

Choose the right path

Prerequisites

Set up the connection

Use cases

Related resources