Skip to main content
Back to the MCP Gateway catalog

MCP Gateway · Catalog

Box icon

Box MCP server

Official

Box MCP is the official Model Context Protocol server for Box, with OAuth and tools that let agents search files and folders, read and upload content, manage comments, and work with metadata templates. Connect it through the Speakeasy MCP Gateway and agents such as Claude, Cursor, and ChatGPT get one governed URL for it, with SSO, RBAC, and a full audit trail.

Category
Productivity
Tools
21
Authentication
OAuth
Connects through
Speakeasy MCP Gateway

Behind the MCP Gateway

Run Box MCP behind the MCP Gateway

One URL for every agent, sign-in through your IdP, RBAC down to the tool, and every Box call inspected and logged.

Deploy on MCP Gateway

Connect from your AI client

Use Box in the clients your teams already use

Setup steps and the controls Speakeasy applies, for each client.

Tools

21 tools

Each tool below can be allowed or denied per team and role at the MCP Gateway, and every call is inspected and logged.

who_am_i

Returns detailed information about the currently authenticated Box user. This tool provides comprehensive user profile data including basic identification, contact information, role details, and account settings.

Example input

Get current user information

{}

search_folders_by_name

Searches for folders by name within Box using keyword matching. This tool helps locate specific folders by their names and can be scoped to search within a particular parent folder. Returns basic folder information including ID, type, and name for each matching folder.

Example inputs (5)

Basic folder search

{
  "folder_name": "Project Documents",
  "limit": 30
}

Search within specific parent folder

{
  "folder_name": "2024 Reports",
  "ancestor_folder_id": "123456789",
  "limit": 50
}

Search for folders with partial name match

{
  "folder_name": "Finance",
  "limit": 20
}

Limited results search

{
  "folder_name": "Marketing Campaign",
  "ancestor_folder_id": "987654321",
  "limit": 10
}

Search in root directory and limit results by date

{
  "folder_name": "Shared Resources",
  "created_at_range": "2023-01-01T00:00:00Z,2023-12-31T23:59:59Z"
}

list_folder_content_by_folder_id

Lists files, folders, and web links contained in a folder. Returns a paginated list of items with at least fields. Fields (id, type, name, etag) are always returned. Use folder_id "0" for the root folder.

Example inputs (3)

Basic folder listing

{
  "folder_id": "0",
  "limit": 50
}

List with specific fields

{
  "folder_id": "123456789",
  "fields": [
    "id",
    "name",
    "type",
    "size",
    "modified_at",
    "created_by"
  ],
  "limit": 100
}

Paginated listing

{
  "folder_id": "987654321",
  "fields": [
    "id",
    "name",
    "type",
    "path_collection"
  ],
  "limit": 30,
  "offset": 60
}

search_files_keyword

Searches for files using keywords and supports metadata filters, file extension filtering (without dots), and field selection. Maps to Box's searchForContent API with comprehensive filtering capabilities.

Example inputs (5)

Basic keyword search (returns core fields only)

{
  "query": "contract agreement",
  "limit": 50
}

Advanced search with additional fields

{
  "query": "quarterly report",
  "file_extensions": [
    "pdf",
    "docx"
  ],
  "ancestor_folder_id": "123456789",
  "fields": [
    "createdAt",
    "modifiedAt",
    "size",
    "createdBy"
  ]
}

Searching by date

{
  "query": "quarterly report",
  "file_extensions": ["pdf", "docx"],
  "ancestor_folder_id": "123456789",
  "created_at_range”: "2023-01-01T00:00:00Z,2023-12-31T23:59:59Z",
  "fields": ["createdAt"]
}

Search with metadata filters and additional fields

{
  "query": "invoice",
  "file_extensions": [
    "pdf"
  ],
  "limit": 30,
  "fields": [
    "contentCreatedAt",
    "pathCollection",
    "metadata"
  ],
  "mdfilters": [
    {
      "scope": "enterprise",
      "templateKey": "invoiceTemplate",
      "filters": {
        "amount": {
          "gt": 1000,
          "lt": 5000
        },
        "status": "approved",
        "department": "finance"
      }
    }
  ]
}

Multi-template metadata search with custom fields

{
  "query": "project document",
  "fields": [
    "modifiedBy",
    "sharedLink",
    "tags",
    "permissions"
  ],
  "mdfilters": [
    {
      "scope": "enterprise",
      "templateKey": "projectTemplate",
      "filters": {
        "priority": "high",
        "deadline": {
          "gt": "2024-01-01"
        }
      }
    },
    {
      "scope": "global",
      "templateKey": "reviewTemplate",
      "filters": {
        "reviewer": "john.doe@company.com"
      }
    }
  ]
}

get_file_content

Extracts and returns file content for files under 50MB. Prefers the markdown representation (preserves document structure for better LLM use) and falls back to extracted text when markdown is not available.

list_tasks

Lists all tasks associated with a specific file. This tool retrieves task information including task details, message, status, and completion rule, due date from the Box platform.

Example input

List tasks for a file

{
  "file_id": "1234567890"
}

get_file_details

Gets comprehensive file information from Box. Returns essential fields by default (id, name, extension, createdBy, modifiedBy, createdAt, modifiedAt). Use 'fields' parameter to request additional properties.

Example inputs (3)

Basic file info

{
  "file_id": "123456789"
}

File with metadata and permissions

{
  "file_id": "987654321",
  "fields": [
    "id",
    "name",
    "size",
    "permissions",
    "tags",
    "metadata",
    "shared_link"
  ]
}

Detailed file analysis

{
  "file_id": "555666777",
  "fields": [
    "id",
    "name",
    "description",
    "file_version",
    "sha1",
    "path_collection",
    "classification",
    "comment_count",
    "has_collaborations"
  ]
}

get_folder_details

Retrieves comprehensive information about a folder in Box. Returns essential fields by default (id, name, createdBy, modifiedBy, createdAt, modifiedAt). Use 'fields' parameter to request additional properties.

Example inputs (3)

Basic folder info

{
  "folder_id": "123456789"
}

Folder with permissions and collaboration settings

{
  "folder_id": "987654321",
  "fields": [
    "id",
    "name",
    "size",
    "permissions",
    "can_non_owners_invite",
    "has_collaborations"
  ]
}

Detailed folder analysis with settings

{
  "folder_id": "555666777",
  "fields": [
    "id",
    "name",
    "description",
    "path_collection",
    "folder_upload_email",
    "allowed_invitee_roles",
    "classification",
    "shared_link",
    "tags"
  ]
}

list_file_comments

Lists all comments on a specific file. Returns a paginated list of comments with configurable fields. Default fields (id, type, message, created_by, created_at) are always returned, but you can specify additional fields as needed.

Example inputs (3)

Basic file comments listing

{
  "file_id": "123456789",
  "limit": 50
}

List with specific fields

{
  "file_id": "987654321",
  "fields": [
    "id",
    "message",
    "created_at",
    "created_by",
    "modified_at"
  ],
  "limit": 100
}

Paginated comments listing

{
  "file_id": "555666777",
  "fields": [
    "id",
    "type",
    "message",
    "tagged_message",
    "created_by"
  ],
  "limit": 25,
  "offset": 50
}

list_item_collaborations

Lists all collaborations for multiple files and folders in a single request.

Example inputs (3)

Basic file collaboration listing

{
  "items": [
    {
      "id": "123456789",
      "type": "file"
    }
  ]
}

Single folder collaboration listing

{
  "items": [
    {
      "id": "987654321",
      "type": "folder"
    }
  ]
}

Multiple items for bulk analysis

{
  "items": [
    {
      "id": "111222333",
      "type": "file"
    },
    {
      "id": "444555666",
      "type": "file"
    },
    {
      "id": "777888999",
      "type": "folder"
    },
    {
      "id": "101112131",
      "type": "folder"
    }
  ]
}

list_metadata_templates

Lists available Box metadata templates so you can discover scope and templateKey for search_files_metadata. Use this first to find templates, then get_metadata_template_schema to get field keys.

get_metadata_template_schema

Returns the schema (including all field keys) for a Box metadata template. Use scope and template_key from list_metadata_templates. The response "fields" array contains "key" values to use as the "fields" parameter in search_files_metadata.

search_files_metadata

Searches for files using SQL-like metadata queries. g. templateKey from list_metadata_templates), fields (field keys from get_metadata_template_schema). ancestor_folder_id defaults to "0" (root) if omitted.

upload_file

Uploads a new file to Box. This tool creates a new file in Box using the provided text content. The file name including the extension must be provided and the extension must match the file content.

upload_file_version

Upload new file version by providing the entire file contents to Box. This tool updates an existing file's version in Box using the given file ID and content. The file ID must correspond to an existing file; otherwise, an error will be returned.

create_folder

Creates new folders in Box.

Example inputs (2)

Create folder in root

{
  "name": "Project Documents"
}

Create folder in specific parent

{
  "name": "Q4 Reports",
  "parent_folder_id": "123456789"
}

create_file_comment

Creates a new comment on a specific file. This tool allows you to add comments to files for collaboration, feedback, or documentation purposes. Comments are visible to all users with access to the file and can be used for team communication and file annotation.

Example inputs (2)

Basic file comment

{
  "file_id": "123456789",
  "message": "This document looks good overall. Please review the financial projections in section 3."
}

Multi-line structured comment

{
  "file_id": "777888999",
  "message": "Review Summary:\n\nContent: Excellent\nStructure: Well organized\nFormatting: Minor issues\nCitations: Missing sources\n\nOverall: Good work, please address the citations before final submission."
}

update_file_properties

Updates file metadata: name, description, tags, and collections.

Example inputs (3)

Rename file

{
  "file_id": "123456789",
  "name": "Q1-Report-2024.pdf"
}

Update description and tags

{
  "file_id": "987654321",
  "description": "Q1 2024 financial report",
  "tags": [
    "finance",
    "2024"
  ]
}

Multiple updates

{
  "file_id": "444555666",
  "name": "Updated-Doc.docx",
  "tags": [
    "project"
  ],
  "collections": [
    {
      "id": "98765"
    }
  ]
}

update_folder_properties

Updates folder metadata: name, description, tags, and collections.

Example inputs (3)

Rename folder

{
  "folder_id": "123456789",
  "name": "Q1 2024 Reports"
}

Update description and tags

{
  "folder_id": "987654321",
  "description": "Q1 2024 financial reports",
  "tags": [
    "finance",
    "2024"
  ]
}

Multiple updates

{
  "folder_id": "444555666",
  "name": "Project Folder",
  "tags": [
    "project"
  ],
  "collections": [
    {
      "id": "98765"
    }
  ]
}

get_file_preview

Displays an interactive preview widget for a Box file directly in chat.

get_preview_page

Use when user asks follow-up question to a file previewed with get_file_preview ("Explain this...", "What does ____ mean?")Returns the current preview page as an image so you can analyze it (figures, text, charts, etc.). You cannot see the page content until you call this tool.

Questions

Frequently asked questions

What is a Box MCP server?
A Box MCP server exposes Box to AI agents as Model Context Protocol tools. Instead of a custom integration per agent, any MCP client can connect to the server and call tools such as who_am_i or search_folders_by_name to work with Box. The server in this catalog is the official Box MCP server, which authenticates with OAuth.
What can you do with Box MCP?
Agents can search files and folders, read and upload content, manage comments, and work with metadata templates. The catalog lists 21 tools for this server, including who_am_i, search_folders_by_name, and list_folder_content_by_folder_id. The full list with descriptions is on this page.
Why put Box MCP behind an MCP gateway?
Connecting the Box MCP server directly to each client means a separate credential per developer, no inventory of who can reach Box through an agent, and no record of what agents did with it. An MCP gateway sits between every agent and the Box server, so sign-in runs through your identity provider, role-based access decides which teams can call which Box tools, and every call is inspected and logged in one place. The Speakeasy MCP Gateway applies those controls to Box and to every other server in your catalog.
How do you connect Box MCP through a gateway?
Add the Box server from the Speakeasy MCP catalog and every agent reaches it through one gateway URL, next to the rest of your approved servers. Authentication uses OAuth 2.1 with PKCE and dynamic client registration, sign-in runs through your identity provider, and role-based access controls decide which teams can use which Box tools. Every prompt, response, and tool call is inspected and logged at the gateway.
How is this different from an unofficial Box MCP?
Community-built Box MCP servers wrap the same Box surface but are not vendor-maintained, and most authenticate with a static credential that gives an agent everything the credential owner can touch. This catalog lists the official Box MCP server, which uses OAuth. Running it behind the Speakeasy MCP Gateway adds SSO, role-based access, and an audit trail of every call.

AI everywhere.

Control here.