> ## 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

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

<Note>
  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.
</Note>

## What you build

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

<CardGroup cols={2}>
  <Card title="Box CLI path" icon="terminal" href="#set-up-the-connection">
    Connect a Client Credentials Grant service account. The agent has its own
    Box identity and can access only the folders shared with it.
  </Card>

  <Card title="Box MCP path" icon="plug" href="#set-up-the-connection">
    Connect the hosted Box MCP server with OAuth. The Box user you authorize
    determines the content available to the agent.
  </Card>
</CardGroup>

## 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                                         |

<Tip>
  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.
</Tip>

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

<Steps>
  <Step title="A Box account you can build on">
    A free [Box developer account](https://account.box.com/signup/developer) 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.
  </Step>

  <Step title="Your agent, installed and working">
    Use any coding or autonomous agent. Confirm it runs and responds before you
    connect Box.

    <Accordion title="Example: installing Codex">
      ```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.
    </Accordion>
  </Step>

  <Step title="Basic terminal familiarity">
    You'll run a handful of commands and edit one or two small config files.
  </Step>
</Steps>

## Set up the connection

<Tabs>
  <Tab title="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.

    <Note>
      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.
    </Note>

    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.

    <Steps>
      <Step title="Install the Box CLI">
        Install the CLI on the machine where the agent runs:

        ```bash theme={null}
        npm install --global @box/cli
        box --version
        ```
      </Step>

      <Step title="Create a Server app in the Developer Console">
        Go to the [Box Developer Console](https://app.box.com/developers/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**.
      </Step>

      <Step title="Authorize the app and copy its credentials">
        Authorize the app in the Developer Console. For enterprise accounts, follow
        the [platform app approval guide](/guides/authorization/platform-app-approval#one-click-authorization)
        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
      </Step>

      <Step title="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:

        ```bash theme={null}
        mkdir -p ~/.box-agent
        chmod 700 ~/.box-agent
        ```

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

        ```json theme={null}
        {
          "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:

        ```bash theme={null}
        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.
      </Step>

      <Step title="Verify the service account">
        Confirm that the active CLI environment uses the service account:

        ```bash theme={null}
        box users:get
        ```

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

          ```text theme={null}
          Name: agent-service
          Login: AutomationUser_..._....@boxdevedition.com
          ```
        </Check>
      </Step>

      <Step title="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.
      </Step>

      <Step title="Connect the agent and verify access">
        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 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:

        ```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 the automation user and list only the folders
        shared with that identity. In the background, it executes these CLI commands:

        ```bash theme={null}
        box users:get
        box folders:items 0
        ```
      </Step>

      <Step title="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:

        ```text theme={null}
        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. ```text theme={null}
           Create a short product-launch brief and a separate notes file in the
           Agent Workspace folder.
           ```
        2. ```text theme={null}
           Read the brief and notes in the Agent Workspace folder, draft a one-page
           status summary, and save it in the same folder.
           ```
      </Step>
    </Steps>

    <Accordion title="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.
    </Accordion>
  </Tab>

  <Tab title="Box MCP (hosted server)">
    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. 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.

    <Info>
      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.
    </Info>

    <Steps>
      <Step title="Enable the integration">
        <Badge>Admin</Badge>

        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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Install the Box plugin">
        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.

        <Note>
          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.
        </Note>
      </Step>

      <Step title="Confirm the MCP server">
        In the same agent chat, enter:

        ```text theme={null}
        /mcp
        ```

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

        <Check>
          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`.
        </Check>
      </Step>

      <Step title="Confirm the agent's access and run a task">
        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.
        ```

        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. ```text theme={null}
           Create a short product-launch brief and a separate notes file in the
           Agent Workspace folder.
           ```
        2. ```text theme={null}
           Read the brief and notes in the Agent Workspace folder, draft a one-page
           status summary, and save it in the same folder.
           ```
      </Step>
    </Steps>

    <Accordion title="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`.
    </Accordion>
  </Tab>
</Tabs>

## 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

<CardGroup cols={2}>
  <Card title="Box CLI docs" icon="terminal" href="https://developer.box.com/guides/cli">
    Command reference and authentication options.
  </Card>

  <Card title="Box MCP server" icon="plug" href="https://developer.box.com/guides/box-mcp">
    Hosted server, supported platforms, and available tools.
  </Card>

  <Card title="Client Credentials Grant" icon="key" href="https://developer.box.com/guides/authentication/client-credentials">
    Details about service-account authentication for the CLI path.
  </Card>

  <Card title="Box AI with the CLI" icon="wand-magic-sparkles" href="https://blog.box.com/how-use-box-ai-box-cli">
    Use Box AI commands for Q\&A and summaries.
  </Card>
</CardGroup>