> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Box

Box's MCP server connects your organization's Box content to Airia agents. Once connected, agents can search, read, and manage files and folders in Box, all while respecting the connected user's existing Box permissions.

Box is a **catalogue server**, so it shows up automatically for organizations in Default Mode. In Custom Mode, an admin needs to approve it on the [Server Management](/mcps/admin-controls/server-management) page before it can be added to a Gateway or Deployment.

## Prerequisites

* A Box account on a plan that includes access to Box's MCP server.
* A **Box Admin** to complete the one-time setup below. Regular Box users can't register the integration themselves.

## One-Time Admin Setup

Box requires an admin to register Airia in the Box Admin Console before anyone in your organization can connect. This only needs to happen once per organization.

1. Sign in to the [Box Admin Console](https://app.box.com/master) as a Box Admin.
2. Click **Integrations** in the left sidebar.
3. Search for **Box MCP server**, hover over the result, and click **Configure**.
4. In the **Additional Configuration** section, click **+ Add Integration Credentials**.
5. Enter a name for the integration, for example `Airia MCP Gateway`, and click **Save**.
6. Expand the entry you just created and copy the **Client ID** and **Client Secret**. You'll need both when connecting Box in Airia.
7. In the **Redirect URI** field of that same entry, enter:

```
https://auth.airia.ai/OAuth/callback
```

8. Under **Access Scopes**, enable **root\_readwrite**, **ai.readwrite**, and **docgen.readwrite**.
9. Click **Save**.

<Note>
  `docgen.readwrite` requires a Box **Enterprise Advanced** license. If your organization is on a lower plan, you can skip it, but the [Doc Gen tools](#doc-gen) won't be usable.
</Note>

<Note>
  Hold onto the Client ID and Client Secret. You'll enter them once in Airia when connecting Box, as covered below.
</Note>

## Connecting Box in Airia

Once the admin setup above is done, anyone building a Gateway or Deployment can add Box as a server:

1. Add **Box** as a server on a Gateway or Deployment.
2. Enter the **Client ID** and **Client Secret** from the admin setup step.
3. Sign in with your own Box account when prompted.

Because Box uses an admin-configured OAuth app, the Client ID and Client Secret are configured in Airia at the Tenant level so this step only happens once for your organization. Each person who connects still signs in with their own Box account, and their access is always personal to them, even when the underlying app registration is shared. See [Tenant vs. Personal Level App Credentials](/mcps/admin-controls/tenant-vs-personal-app-credentials) for more on how this works.

## What You Can Do With Box

Once connected, agents can use Box to:

* Manage files and folders, including creating, moving, renaming, and deleting items
* Search content by keyword or metadata filter
* Ask questions about one or more files using Box's built in AI features
* Extract structured or freeform metadata from files
* Add comments and tasks for collaboration
* Create and manage Box Hubs
* Upload files and manage versions

<Note>
  Box tools always act on behalf of the connected user and respect that user's existing Box permissions. If someone can't access a file in Box directly, connecting Box to Airia doesn't change that.
</Note>

See [Tools and Required Scopes](#tools-and-required-scopes) below for the full list of tools behind these capabilities.

## Tools and Required Scopes

Box's scopes are broader than most MCP servers you'll see documented here, just three scopes cover every tool:

| Scope              | Covers                                                   |
| ------------------ | -------------------------------------------------------- |
| `root_readwrite`   | Files, folders, search, collaboration, and hubs          |
| `ai.readwrite`     | Box AI question-answering and metadata extraction        |
| `docgen.readwrite` | Doc Gen (requires a Box **Enterprise Advanced** license) |

Grant all three during the [One-Time Admin Setup](#one-time-admin-setup) above to unlock everything below.

<Note>
  Tools marked with **†** only work on items that meet all of the following: no external collaborators on the item itself, no shared link on the item itself, and no external collaborators or shared links on any parent folder up to the root.
</Note>

### User and Authentication

| Tool       | What it does                                                             | Scope required   |
| ---------- | ------------------------------------------------------------------------ | ---------------- |
| `who_am_i` | Returns detailed information about the currently authenticated Box user. | `root_readwrite` |

### Files and Folders

#### Read-only

| Tool                               | What it does                                                                                        | Scope required   |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------- |
| `get_download_url`                 | Issues a temporary, single-use URL for downloading a binary file from Box.                          | `root_readwrite` |
| `get_file_content`                 | Returns the content of a file stored in Box.                                                        | `root_readwrite` |
| `get_file_details`                 | Returns detailed file information, including metadata, permissions, and version details.            | `root_readwrite` |
| `get_file_preview`                 | Returns the preview widget for a file stored in Box.                                                | `root_readwrite` |
| `get_folder_details`               | Retrieves detailed folder information, including metadata, permissions, and collaboration settings. | `root_readwrite` |
| `list_folder_content_by_folder_id` | Lists files, folders, and web links in a folder. Use `folder_id` `"0"` for the root folder.         | `root_readwrite` |

#### Write

| Tool                         | What it does                                                                                  | Scope required   |
| ---------------------------- | --------------------------------------------------------------------------------------------- | ---------------- |
| `copy_file` †                | Copies a file to a destination folder.                                                        | `root_readwrite` |
| `copy_folder` †              | Copies a folder to a destination parent folder.                                               | `root_readwrite` |
| `create_folder` †            | Creates a folder in Box.                                                                      | `root_readwrite` |
| `create_metadata_template`   | Creates an enterprise metadata template from a `display_name` and an optional `fields` array. | `root_readwrite` |
| `get_upload_url`             | Issues a temporary, single-use URL for uploading a binary file to Box.                        | `root_readwrite` |
| `move_file` †                | Moves a file to a destination folder. The file ID stays the same.                             | `root_readwrite` |
| `move_folder` †              | Moves a folder to a new parent. The folder ID stays the same.                                 | `root_readwrite` |
| `set_file_metadata` †        | Creates or updates custom metadata on a file for a template.                                  | `root_readwrite` |
| `set_folder_metadata` †      | Creates or updates custom metadata on a folder for a template.                                | `root_readwrite` |
| `update_file_properties` †   | Updates a file's name, description, tags, and collections.                                    | `root_readwrite` |
| `update_folder_properties` † | Updates a folder's name, description, tags, and collections.                                  | `root_readwrite` |
| `update_metadata_template`   | Updates a metadata template's schema, for example adding, editing, or removing fields.        | `root_readwrite` |
| `upload_file` †              | Uploads a new file to Box.                                                                    | `root_readwrite` |
| `upload_file_version` †      | Uploads a new version of an existing file.                                                    | `root_readwrite` |

<Note>
  `get_download_url` and `get_upload_url` require the agent to make a direct network request to transfer the file, which only works in code-executing environments. If your client allowlists domains, it needs `upload.box.com`, `upload.app.box.com`, `upload.ent.box.com`, `dl.boxcloud.com`, and `public.boxcloud.com` (these vary by Box Zone).
</Note>

### Search

| Tool                           | What it does                                                                       | Scope required   |
| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------- |
| `get_metadata_template_schema` | Returns the schema and field keys for a metadata template.                         | `root_readwrite` |
| `list_metadata_templates`      | Lists available Box metadata templates, enterprise or global.                      | `root_readwrite` |
| `search_files_keyword`         | Searches for files by keyword, with metadata filters and file-extension filtering. | `root_readwrite` |
| `search_files_metadata`        | Searches for files using SQL-like metadata queries, with folder scoping.           | `root_readwrite` |
| `search_folders_by_name`       | Searches for folders by name using keyword matching.                               | `root_readwrite` |

### Collaboration

#### Read-only

| Tool                       | What it does                                                          | Scope required   |
| -------------------------- | --------------------------------------------------------------------- | ---------------- |
| `list_file_comments`       | Lists all comments on a file.                                         | `root_readwrite` |
| `list_item_collaborations` | Lists all existing collaborations on an item.                         | `root_readwrite` |
| `list_tasks`               | Lists all tasks for a file, including status, message, and due dates. | `root_readwrite` |

#### Write

| Tool                     | What it does                                                                                       | Scope required   |
| ------------------------ | -------------------------------------------------------------------------------------------------- | ---------------- |
| `add_file_shared_link`   | Creates or updates a shared link for a file. Can add external collaborators; off by default.       | `root_readwrite` |
| `add_folder_shared_link` | Creates or updates a shared link for a folder. Can add external collaborators; off by default.     | `root_readwrite` |
| `create_collaboration`   | Invites a user or group to a file, folder, or hub. Can add external collaborators; off by default. | `root_readwrite` |
| `create_file_comment` †  | Creates a comment on a file.                                                                       | `root_readwrite` |
| `update_collaboration`   | Updates a file, folder, or hub collaboration. Can add external collaborators; off by default.      | `root_readwrite` |

### Box AI

| Tool                                                    | What it does                                                                                                                                                                    | Scope required |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `ai_extract_freeform`                                   | Extracts metadata from one or more files using a natural-language prompt instead of a fixed template. Processes up to 2 MB of a file's text representation.                     | `ai.readwrite` |
| `ai_extract_structured`                                 | Extracts structured key-value metadata using the Box AI Enhanced Extract Agent and custom field definitions.                                                                    | `ai.readwrite` |
| `ai_extract_structured_from_fields`                     | Extracts structured metadata from one or more files using custom field definitions (`string`, `date`, `float`, `enum`, or `multiSelect`).                                       | `ai.readwrite` |
| `ai_extract_structured_from_fields_enhanced`            | Same as `ai_extract_structured_from_fields`, but with the Enhanced Extract Agent. Only use when explicitly requested, it costs more than the standard extract tools.            | `ai.readwrite` |
| `ai_extract_structured_from_metadata_template`          | Extracts structured metadata using an existing Box metadata template, identified by `template_key` and `scope` (`enterprise` or `global`).                                      | `ai.readwrite` |
| `ai_extract_structured_from_metadata_template_enhanced` | Same as `ai_extract_structured_from_metadata_template`, but with the Enhanced Extract Agent. Only use when explicitly requested, it costs more than the standard extract tools. | `ai.readwrite` |
| `ai_qa_hub`                                             | Asks a question about a Box hub and returns an answer based on the hub's content, with citations when available.                                                                | `ai.readwrite` |
| `ai_qa_multi_file`                                      | Asks a question about multiple files, with citations when available.                                                                                                            | `ai.readwrite` |
| `ai_qa_single_file`                                     | Asks a question about a single file, with citations when available. Processes up to 2 MB of the file's text representation.                                                     | `ai.readwrite` |

### Hubs

#### Read-only

| Tool              | What it does                                               | Scope required   |
| ----------------- | ---------------------------------------------------------- | ---------------- |
| `get_hub_details` | Retrieves detailed information about a specific hub.       | `root_readwrite` |
| `get_hub_items`   | Gets the files and folders associated with a specific hub. | `root_readwrite` |
| `list_hubs`       | Lists all hubs the authenticated user can access.          | `root_readwrite` |

#### Write

| Tool                 | What it does                                                                                              | Scope required   |
| -------------------- | --------------------------------------------------------------------------------------------------------- | ---------------- |
| `add_items_to_hub` † | Adds files, folders, or web links to a hub.                                                               | `root_readwrite` |
| `copy_hub` †         | Creates a copy of an existing hub, including its structure and settings. The original hub isn't modified. | `root_readwrite` |
| `create_hub`         | Creates a hub.                                                                                            | `root_readwrite` |
| `update_hub` †       | Updates a hub's title and description.                                                                    | `root_readwrite` |

### Doc Gen

<Note>
  Every tool in this category needs `docgen.readwrite`, which requires a Box **Enterprise Advanced** license regardless of which scope is granted in Airia.
</Note>

#### Read-only

| Tool                        | What it does                                                       | Scope required     |
| --------------------------- | ------------------------------------------------------------------ | ------------------ |
| `get_docgen_template_by_id` | Retrieves details about a Doc Gen template.                        | `docgen.readwrite` |
| `list_docgen_templates`     | Lists all Box Doc Gen templates the authenticated user can access. | `docgen.readwrite` |

#### Write

| Tool                     | What it does                                                                                 | Scope required     |
| ------------------------ | -------------------------------------------------------------------------------------------- | ------------------ |
| `create_docgen_batch`    | Generates documents from a Doc Gen template by filling placeholder tags with provided data.  | `docgen.readwrite` |
| `create_docgen_template` | Marks a Box `.docx` or `.pptx` file as a Doc Gen template for automated document generation. | `docgen.readwrite` |

## Learn More

* [Box MCP Server Setup Guide](https://developer.box.com/guides/box-mcp/setup)
* [Box MCP Server Available Tools](https://developer.box.com/guides/box-mcp/tools)
* [Box Admin Console](https://app.box.com/master)