Connect an AI agent to Box

Give coding and autonomous agents secure, scoped access to Box content through the Box CLI or the Box MCP server.

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

1. 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.

2. 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.

3. 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)

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.

1. Install the Box CLI

   Install the CLI on the machine where the agent runs:

   npm install --global @box/cli
   box --version
   
2. Create a Server app in the Developer Console

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

   1. Enter an App Name (for example, agent-service).
   2. Under App Type, choose Server. If the option displays, select Client Credentials Grant.
   3. Click Create.
3. 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
4. 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.

5. 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: [e-mail]
   
6. 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.

7. 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
   
8. 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:

   1. Create a short product-launch brief and a separate notes file in the
      Agent Workspace folder.
      
   2. 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.

Box MCP (hosted server)

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.

1. Enable the integration

   Admin

   1. Sign in to the Box Admin Console.
   2. 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.
   3. 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.
2. 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 [e-mail]. 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.

3. 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.

4. 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.

5. 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:

   1. Create a short product-launch brief and a separate notes file in the
      Agent Workspace folder.
      
   2. 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.

Related resources

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.