> ## Documentation Index > Fetch the complete documentation index at: https://developer.box.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect an AI agent to Box > Connect a coding or autonomous agent to a Box developer account through OAuth with the Box CLI or 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 an isolated Box developer account through either the Box CLI or the hosted Box MCP server. The examples use [Codex](https://developers.openai.com/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. Sign in with OAuth on the agent's local computer, a remote host, or a headless container. 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](https://account.box.com/signup/developer) 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 Create a free [Box developer account](https://account.box.com/signup/developer) 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. Use any coding or autonomous agent. Confirm it runs and responds before you connect Box. ```bash theme={null} # 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. 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 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 CLI on the machine where the agent runs: ```bash theme={null} npm install --global @box/cli box --version ``` Choose the instructions that match where the Box CLI and agent run. Run the standard login command on the same computer as the agent: ```bash theme={null} 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. Start a manual-code login on the remote runtime: ```bash theme={null} 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: 1. Copy the URL and open it in a browser on your local computer. 2. Sign in with your isolated developer-account user and select **Grant Access to Box**. 3. 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. 4. 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](/guides/cli/headless-login). 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. Confirm that the active CLI session uses your developer-account user: ```bash theme={null} 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. Add instructions for your agent. In Codex, add them to `AGENTS.md` in the working directory: ```markdown theme={null} ## 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: ```text theme={null} 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: ```bash theme={null} box users:get me box folders:items 0 ``` Enter each prompt in the agent chat in order; each builds on the last: 1. ```text theme={null} Create a short product-launch brief and a separate notes file in the root of my Box account. ``` 2. ```text theme={null} 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. ``` * **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](https://modelcontextprotocol.io) 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](/guides/box-mcp/index#platform-setup-guides) for other clients. Admin You are the admin of your free developer account, so you can complete this step yourself: 1. Sign in to the [Box Admin Console](https://app.box.com/master). 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. 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. Open the Codex app or start a Codex CLI chat. In the chat input, enter: ```text theme={null} /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. In the same agent chat, enter: ```text theme={null} /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`. In the agent chat, enter: ```text theme={null} 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: 1. ```text theme={null} Create a short product-launch brief and a separate notes file in the root of my Box account. ``` 2. ```text theme={null} 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. ``` * **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](/platform/user-types), [create an App User](/guides/users/create-app-user), [select an authentication method](/guides/authentication/select), and [Platform App approval](/guides/authorization/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. ## Related resources Command reference and authentication options. Complete OAuth when the CLI runs on a VPS or in a container. Hosted server, supported platforms, and available tools. Compare Managed Users, Service Accounts, and App Users.