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 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.
- Sign in to the Box Admin Console as a Box Admin.
- Click Integrations in the left sidebar.
- Search for Box MCP server, hover over the result, and click Configure.
- In the Additional Configuration section, click + Add Integration Credentials.
- Enter a name for the integration, for example
Airia MCP Gateway, and click Save.
- Expand the entry you just created and copy the Client ID and Client Secret. You’ll need both when connecting Box in Airia.
- In the Redirect URI field of that same entry, enter:
https://auth.airia.ai/OAuth/callback
- Under Access Scopes, enable root_readwrite, ai.readwrite, and docgen.readwrite.
- Click Save.
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 won’t be usable.Hold onto the Client ID and Client Secret. You’ll enter them once in Airia when connecting Box, as covered below.
Connecting Box in Airia
Once the admin setup above is done, anyone building a Gateway or Deployment can add Box as a server:
- Add Box as a server on a Gateway or Deployment.
- Enter the Client ID and Client Secret from the admin setup step.
- 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 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
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.
| 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) |
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.
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 |
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).
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
Every tool in this category needs docgen.readwrite, which requires a Box Enterprise Advanced license regardless of which scope is granted in Airia.
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
