Skip to main content
Back to the Box MCP server

MCP Gateway · Codex

Box icon

Connect Box to Codex

Reviews sometimes hinge on a document that lives in Box: a security questionnaire, a vendor spec, a signed-off design. With Box behind the Speakeasy MCP Gateway, Codex can check that file's details and contents during review, tidy the names and tags on files a job produced, and confirm which Box account it is acting as. Agent hooks let Speakeasy allow or deny each Box call first.

Category
Productivity
Tools
21
Authentication
OAuth
Codex
CLI and ChatGPT desktop app

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

Before you start

What Box needs first

A Box Admin or Co-Admin does the Box side of the setup.

  • You need a Box Admin or Co-Admin account for the enterprise.
  • Box AI tools need an eligible Box AI plan or purchased Box AI Units. Doc Gen needs an Enterprise Advanced license.
  • Box meters and bills API calls made with the integration credentials.

In Box

  1. Sign in to the Box Admin Console.
  2. Enable the Box AI API or Box Doc Gen if users need those tools.
  3. Under Integrations, add credentials for the Custom Box MCP Server.
  4. Set the Speakeasy redirect URI and copy the Client ID and Client Secret.
  5. Choose access scopes and save.
Full Box setup guide in the docs

Set up

Add Box to Codex in 4 steps

  1. 01

    Add Box from the catalog

    An admin finds Box in the MCP Catalog (MCP Gateway > MCP > Catalog) and clicks Add. Speakeasy registers the vendor's server as a remote MCP server and proxies sessions to it. Nothing is copied or re-hosted.

    Box uses OAuth. Servers that support dynamic client registration get their OAuth configuration applied automatically.

    Where MCP-scoped policies are enabled, the install offers a recommended risk policy for the new server that detects secrets and PII and inspects tool requests and responses.

  2. 02

    Choose who can use Box

    Give teams the mcp:connect scope on the Box server through team access or a role. The organization gateway works out each person's servers from their live access, so granting access adds Box to their gateway on the next call, and removing it takes it away.

  3. 03

    Connect Codex

    Add the gateway as an MCP server, then log in.

    Run the first command with your organization gateway URL.

    Run the second command to sign in.

    codex mcp add 'speakeasy' \
      --url 'https://<organization host>/mcp/gateway/<organization slug>'
    codex mcp login 'speakeasy'
  4. 04

    Sign in and use Box from Codex

    The first time Codex connects, it opens a browser so the person can sign in to Speakeasy through your identity provider.

    Box needs its own OAuth grant, so each person connects it once. Until they do, Box calls fail while the rest of the gateway keeps working.

    From then on, Box's tools appear in Codex, limited to what the person's access allows, and every call lands in the gateway's tool logs.

To roll it out to a team, a ChatGPT workspace admin imports the plugin marketplace under Admin > Plugins and sets an installation policy per role. Imported plugins reach nobody until a policy is set.

Use cases

What Codex users do with Box

Check the document cited in review

When a pull request points to a Box file, Codex reads its details, such as who last modified it and when, then its content, so the review uses the current version.

get_file_detailsget_file_content

Name and tag generated files

After a build drops reports into Box, Codex renames them with the release number, keeps the original extension and adds tags so people can find them later.

update_file_properties

Confirm the connected Box account

If Codex can't see a folder, ask it which Box user it is signed in as, with that account's role details, before anyone starts changing permissions.

who_am_i

Tools

21 tools

Each Box tool can be allowed or denied per team and role at the MCP Gateway before Codex sees it.

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"
}
See all 21 tools

Control

What Speakeasy can see and stop in Codex

The gateway covers every client the same way. The rest depends on what Codex exposes to Speakeasy.

Tool logs

Gateway

Every Box call is logged with the person and the client that made it.

Access by role

Gateway

People reach only the Box tools their team or role allows.

Request and response blocking

Gateway

A risk policy scoped to Box can reject a tool request before it reaches the server, or withhold a result from Codex. MCP-scoped policies are enabled per organization.

Prompt and tool-call blocking

Codex

Agent hooks send each prompt and tool call to Speakeasy, which allows or denies it before Codex runs it.

User attribution

Codex

An [otel] block in ~/.codex/config.toml sends telemetry to Speakeasy. Export is off by default.

Budgets

Codex

Spend limits can block Codex traffic once a budget is reached.

Device agent and MDM

Codex

The device agent keeps Codex's configuration in sync on managed laptops.

  • Codex cloud tasks and GitHub code review run off the device. Neither the plugin nor OpenTelemetry covers them; OpenAI's Compliance Logs record them after the fact.
  • The workspace rollout needs a ChatGPT Business, Enterprise or Edu admin.

Questions

Frequently asked questions

Who has to set up Box before Codex can use it?
A Box Admin or Co-Admin adds credentials for the Custom Box MCP Server in the Box Admin Console, sets the Speakeasy redirect URI and chooses access scopes. Developers then connect their own Box accounts.
Is Box activity from Codex attributed to a person?
Yes, once telemetry is on. An [otel] block in ~/.codex/config.toml sends telemetry to Speakeasy, and export is off by default.
How do Codex users get Box?
An admin adds Box from the Speakeasy MCP Catalog and grants access by team or role. Add the gateway as an MCP server, then log in. Each person then sees only the Box tools their access allows.
Are Box calls from Codex logged?
Yes. Box calls go through the MCP Gateway, which logs each tool call and attributes it to the person and the client that made it.

Connect more

Box in other clients

AI everywhere.

Control here.