Secure Box access for AI agents

Files, folders, metadata, shared links, hubs, Doc Gen, and Box AI via Box's official MCP server

Through Box, agents can read and write files and folders, manage metadata and shared links, work with hubs and Doc Gen, and run Box AI over your content — every call runs through your policies and is logged for audit.

Server URL: https://mcp.box.com

Setup

Navigate to Resources and click Add Resource
Select Box from the catalog
Provide your Box OAuth app credentials (see Bring your own app)
Click Add

Each user connects their own Box account via OAuth when they first use a Box tool; there is no shared service account. Navigate to Connections to manage linked accounts.

Credential modes

Box supports one mode:

Bring your own app: a Box OAuth 2.0 app owned by your organization. Box does not support dynamic client registration, so you supply a Client ID and Client Secret from Box.

See Credential modes for the full comparison.

Bring your own app

Box offers two ways to get the Client ID and Client Secret for that app. Its preferred route is the Custom Box MCP Server integration it ships in the Admin Console, because there is no app to build and no scopes to wire up by hand. Create your own OAuth app in the Developer Console instead if you need an app your organization controls end to end. The gateway accepts credentials from either route and cannot tell them apart.

Start on the SecureAuth side. In the Agent Authority console, go to Resources → Add Resource → Box and copy the redirect URI shown on the page. Box is bring-your-own-app only, so the credentials form opens as soon as you select it — there's no mode to pick. Keep the page open; you return to it at the end.

Option A: the Custom Box MCP Server integration

This route needs Box Admin Console access.

In Box, open the Admin Console and click Integrations in the sidebar
Open the Box Integrations & Clients tab and scroll to Individual Integration Controls
Set the Categories filter to MCP (or search for Box MCP), hover over Custom Box MCP Server, and click Configure
Under Configuration, click + Add Integration Credentials, give the entry a name such as SA Agent Authority, and click Save
Expand the new entry and copy the Client ID and Client Secret
In Redirect URI, paste the redirect URI you copied from the Agent Authority console
Under Access Scopes and Administrative Actions, enable the scopes listed in Required scopes

Option B: your own Developer Console app

Any developer in the Box enterprise can do this; Admin Console access is not required.

In the Box Developer Console, click Create Platform App → Custom App and choose User Authentication (OAuth 2.0):

Under Configuration → OAuth 2.0 Redirect URIs, add the redirect URI you copied
Under Configuration → Application Scopes, enable Read and write all files and folders stored in Box (root_readwrite), Manage AI (ai.readwrite), and Manage DocGen (docgen.readwrite)
Copy the Client ID and Client Secret from Configuration → OAuth 2.0 Credentials

Finish in the Agent Authority console

Whichever route you took, paste the Client ID and Client Secret into the Box configure page, then click Add. Leave Token Endpoint Authentication on Auto-detect — Box works with the detected default.

Depending on your Box enterprise settings, an admin may need to authorize the app once at Admin Console → Apps → Custom Apps Manager before users can connect.

Available tools

Tool	Description
`who_am_i`	Returns detailed information about the currently authenticated Box user
`get_download_url`	Issues a temporary, single-use URL for downloading binary files from Box
`get_file_content`	Returns the content of a file stored in Box
`get_file_details`	Returns detailed file information, including metadata, permissions, and versions
`get_file_preview`	Displays an interactive preview widget for a Box file
`get_preview_page`	Returns the current preview page as an image for analysis
`get_folder_details`	Retrieves detailed folder information, including permissions and collaborations
`list_folder_content_by_folder_id`	Lists files, folders, and web links in a folder (paginated)
`copy_file`	Copies an existing file to a destination folder
`copy_folder`	Copies an existing folder to a destination parent folder
`create_folder`	Creates a folder in Box
`create_metadata_template`	Creates an enterprise metadata template
`get_upload_url`	Issues a temporary, single-use URL for uploading binary files to Box
`move_file`	Moves an existing file to a destination folder
`move_folder`	Moves a folder to a new parent
`set_file_metadata`	Creates or updates (upserts) custom metadata on a file for a template
`set_folder_metadata`	Creates or updates (upserts) custom metadata on a folder for a template
`update_file_properties`	Updates file name, description, tags, and collections
`update_folder_properties`	Updates folder name, description, tags, and collections
`update_metadata_template`	Updates a metadata template by scope and template key
`upload_file`	Uploads a new file to Box
`upload_file_version`	Uploads a new file version by providing the entire file contents
`get_metadata_template_schema`	Returns the schema and field keys for a metadata template
`list_metadata_templates`	Lists available Box metadata templates (enterprise or global)
`search_files_keyword`	Searches for files using keywords
`search_files_metadata`	Searches for files using SQL-like metadata queries
`search_folders_by_name`	Searches for folders in Box by name using keyword matching
`list_file_comments`	Lists all comments on a file
`list_item_collaborations`	Lists all existing collaborations on an item
`list_tasks`	Lists all tasks for a file, including status, message, and due dates
`add_file_shared_link`	Creates or updates a shared link for a Box file
`add_folder_shared_link`	Creates or updates a shared link for a Box folder
`create_collaboration`	Invites a user or group to a file, folder, or hub
`create_file_comment`	Creates a comment on a file
`update_collaboration`	Updates a file, folder, or hub collaboration
`ai_extract_freeform`	Extracts metadata from files using Box AI with natural-language prompts
`ai_extract_structured`	Extracts structured key-value metadata from files using Box AI
`ai_extract_structured_from_fields`	Extracts structured metadata from files using custom field definitions
`ai_extract_structured_from_fields_enhanced`	Extracts structured metadata using the Enhanced Extract Agent
`ai_extract_structured_from_metadata_template`	Extracts structured metadata from files using an existing template
`ai_extract_structured_from_metadata_template_enhanced`	Extracts metadata using template and Enhanced Extract Agent
`ai_qa_hub`	Asks a question about a Box hub and returns an answer based on content
`ai_qa_multi_file`	Asks a question about multiple files using Box AI
`ai_qa_single_file`	Asks a question about a single file using Box AI
`get_hub_details`	Retrieves detailed information about a specific hub
`get_hub_items`	Gets items (files and folders) associated with a specific hub
`list_hubs`	Lists all hubs that the authenticated user can access
`add_items_to_hub`	Adds files, folders, or web links to a hub
`copy_hub`	Creates a copy of an existing hub, including structure and settings
`create_hub`	Creates a hub
`update_hub`	Updates the title and description of a hub
`get_docgen_template_by_id`	Retrieves details about a Doc Gen template
`list_docgen_templates`	Lists all Box Doc Gen templates the authenticated user can access
`create_docgen_batch`	Generates documents from a Doc Gen template
`create_docgen_template`	Marks a Box file as a Doc Gen template

Which of these actually appear depends on your Box enterprise's MCP tool-access settings and licensing. The gateway syncs the live list from Box after the first account connects, so the Box AI, Hubs, and Doc Gen tools show up only when your plan and admin settings enable them.

Required scopes

root_readwrite: read and write all files and folders stored in Box
ai.readwrite: use Box AI for Q&A and metadata extraction
docgen.readwrite: manage and run Box Doc Gen (requires an Enterprise Advanced license; remove this scope from the app if your plan does not include Doc Gen)

Policy examples

Rules are evaluated top to bottom and the first match wins, so a restrictive recipe needs a catch-all deny scoped to Box below its allow rules. Allow rules alone restrict nothing: your org starts with a seeded Allow all rule, and anything your allows don't cover falls through to it. New rules are inserted at the top of the list, so create rules in reverse order (catch-all deny first) or drag them into place afterwards. See Policies for the full model.

Read-only access. Deny get_upload_url, then allow who_am_i, get_*, list_*, and search_*, then deny *. The get_upload_url deny must sit above the get_* allow: it matches get_* but mints a temporary upload URL, and the upload that follows goes straight to Box without passing through the gateway.
Content without sharing. Deny add_file_shared_link, add_folder_shared_link, create_collaboration, and update_collaboration. Deny-only rules work against the seeded Allow all as long as they sit above it.
No AI processing. Deny ai_*.
Doc Gen workflows only. Allow list_docgen_templates, get_docgen_template_by_id, and create_docgen_batch, then deny * below them so nothing else on Box falls through to Allow all.

Next steps

Create a policy — start from the read-only pattern in Policy examples above.
Policies — how rule order, scoping, and the seeded Allow all rule interact.
Connections — manage the Box accounts your users have linked.

Secure Box access for AI agents

On this page