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 page before it can be added to a Gateway or Deployment.

What It Can Do

Category	Capability
Account	Look up details about the currently connected Box user.
Files and Folders	Create, move, rename, copy, and delete files and folders. Upload new files and new versions, and create or update custom metadata.
Search	Search for files by keyword or metadata filter, and search for folders by name.
Collaboration	Add comments and tasks to files, and manage collaborators and shared links.
Box AI	Ask questions about one or more files or a Hub, and extract structured or freeform metadata, using Box’s built-in AI.
Hubs	Create, copy, and update Box Hubs, and manage the files, folders, and links inside them.
Doc Gen	Generate documents from a Doc Gen template. Requires a Box Enterprise Advanced license.

See Tools and Required Scopes below for the full list of tools behind these capabilities.

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.

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. Open the Box MCP server integration

   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.

2. Add integration credentials

   In the Additional Configuration section, click + Add Integration Credentials. Enter a name for the integration, for example Airia MCP Gateway, and click Save.

3. Copy the Client ID and Client Secret

   Expand the entry you just created and copy the Client ID and Client Secret. You’ll need both when connecting Box in Airia.

4. Set the redirect URI

   In the Redirect URI field of that same entry, enter:

   https://auth.airia.ai/OAuth/callback
   
5. Enable access scopes and save

   Under Access Scopes, enable root_readwrite, ai.readwrite, and docgen.readwrite, then 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.

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

   Add Box as a server on a Gateway or Deployment.

2. Enter the Client ID and Client Secret

   Enter the Client ID and Client Secret from the admin setup step above.

3. Sign in with your Box account

   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.

Tools and Required Scopes

Box’s scopes are broader than most MCP servers 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 above so every tool below is available.

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

Troubleshooting

Doc Gen tools aren't available or fail

Cause: docgen.readwrite requires a Box Enterprise Advanced license. Granting the scope in Airia doesn’t help if your organization’s Box plan doesn’t include it.

Fix: Confirm your organization has Enterprise Advanced. If it doesn’t, the Doc Gen tools stay unavailable; every other tool still works normally.

get_download_url or get_upload_url calls fail

Cause: Both tools return a URL the agent has to fetch or upload to directly, which only works in code-executing environments. If your client allowlists domains, the transfer domain may also be blocked.

Fix: Confirm your client can execute code, then allowlist upload.box.com, upload.app.box.com, upload.ent.box.com, dl.boxcloud.com, and public.boxcloud.com (these vary by Box Zone).

A tool marked † fails with a permissions error

Cause: Tools marked † only work on items with no external collaborators or shared links, on the item itself or on any parent folder up to the root.

Fix: Remove the external collaborator or shared link from the item and its parent folders, or point the agent at a different item that meets that condition.

Learn More

• Box MCP Server Setup Guide
• Box MCP Server Available Tools
• Box Admin Console