Terminal
Terminal/Skill
Starting point for any Box task: sets up Box MCP or CLI access, picks the right tool, and troubleshoots common Box errors.
By Box
Works with
npx skills add box/skills --skill boxThis is the foundation skill for any Box task. It routes a request to the right tool (MCP, CLI, or REST) and the right domain reference. Use it to:
Always start here—even when the user does not name a specific tool—then route to the deeper reference.
First confirm which resources you actually have access to and are able to access. After, use this table to pick the right tool for the operation:
| Operation type | Prefer | Rationale |
|---|---|---|
| Most agent workflows (search, AI, content management, metadata, hubs) | MCP | Structured I/O, concurrent-safe, covers the common cases |
| Bulk operations (batch moves, folder trees, batch metadata) | CLI | Compact output, --fields filtering, full API surface without requiring manual REST auth |
| Verification and smoke tests | CLI | Reproducible, user can copy-paste commands |
| Operations outside MCP scope | CLI | Full API coverage |
| Last-resort fallback when MCP is unavailable and CLI is unavailable or not an option | Direct REST | Only after explicit user confirmation and REST auth setup guidance |
| Building application code (SDK/REST endpoints, webhook handlers) | SDK or REST in code | Not agent tooling — write code the user ships |
The table above is the single source of truth for tool selection — the sections below reference it rather than restate it. When tooling is unavailable, escalate in this order: guide the user through MCP setup first, then CLI setup, and only fall back to direct REST as a last resort after the user explicitly confirms REST fallback is acceptable.
Choose which reference files to read based on what the user needs:
| If the user needs... | Read first | Pair with | Minimal verification |
|---|---|---|---|
| Uploads, folders, listings, downloads, previews, moves, or metadata | references/content-workflows.md | references/auth-and-setup.md | Read-after-write call using the same actor |
| Sharing, collaborations (users/groups), or shared links | references/collaboration.md | references/content-workflows.md, references/auth-and-setup.md | List collaborations before and after changes |
| Finding files or folders (keyword, folder name, metadata search) | references/mcp-search.md | references/auth-and-setup.md | Confirm item details before acting |
| Box AI Q&A, summarization, extraction, or document retrieval | references/ai-and-retrieval.md | references/auth-and-setup.md | Retrieval-quality check before answer formatting |
| Box Hubs — creating, curating, or querying a hub | references/mcp-hubs.md | references/ai-and-retrieval.md, references/auth-and-setup.md | Confirm hub items after changes |
| Document generation from templates (Doc Gen) | references/mcp-doc-gen.md | references/content-workflows.md, references/auth-and-setup.md | Confirm template and destination before batch |
| Organizing, reorganizing, or batch-moving files across folders; bulk metadata tagging; migrating folder structures | references/bulk-operations.md | references/content-workflows.md, references/auth-and-setup.md, references/ai-and-retrieval.md | Inventory source, verify move count matches plan |
| Event-driven ingestion, new-file triggers, or webhook debugging | references/webhooks-and-events.md | references/auth-and-setup.md, references/troubleshooting.md | Signature check plus duplicate-delivery test |
| 401, 403, 404, 409, 429, missing content, or wrong-actor bugs | references/troubleshooting.md | references/auth-and-setup.md | Reproduce with the exact actor, object ID, and endpoint |
| Unsure which workflow applies | references/workflows.md | references/auth-and-setup.md | Choose the smallest Box object/action pair first |
The Box MCP server is the default tooling for agent workflows. It provides structured I/O, is concurrent-safe, and covers the common cases (search, Box AI, content management, metadata, hubs). See the tool selection table above for when to prefer it over CLI or REST.
who_am_i. If it fails, complete the client-provided MCP OAuth flow and retry.references/auth-and-setup.md for MCP setup steps and walk the user through setup before considering other tooling.The updated/maintained list of Box MCP tools is documented at https://docs.box.com/en/box-mcp/tools. If an expected tool is missing or unavailable, see references/troubleshooting.md (MCP tool missing section) for diagnostic steps and admin-console enablement.
get_file_details before operating on a file — it confirms the file exists and shows current state.The Box MCP capabilities are documented in focused reference files. Use the domain routing table above to pick the right one for the task:
| MCP category | Reference |
|---|---|
| Files, folders, uploads, downloads, previews, metadata | references/content-workflows.md |
| Search (keyword, folder, metadata) | references/mcp-search.md |
| Collaborations (users/groups) and shared links | references/collaboration.md |
| Box AI Q&A, extraction, structured metadata extraction, and agents | references/ai-and-retrieval.md |
| Box Hubs creation, item management, and hub-level Q&A | references/mcp-hubs.md |
| Box Doc Gen templates and document generation batches | references/mcp-doc-gen.md |
The tool selection table above governs when to reach for the CLI or direct REST. Both rank below MCP: CLI for operations outside MCP's scope or that need compact, field-filtered output, and direct REST only as a last-resort fallback after explicit user confirmation.
box users:get me --json. Record whether CLI is available.box users:get me --json.references/box-cli.md for CLI-first auth, smoke-test commands, safe verification patterns, and serial-execution constraints.Direct REST is the last-resort fallback per the tool selection table — only when MCP and CLI are both unavailable or declined.
Building application code (SDK/REST endpoints, webhook handlers) the user ships is a separate case — that is code you write, not agent tooling. Prefer an official Box SDK when one already exists in the codebase or for the target language.
BOX_ACCESS_TOKEN) and safe auth handling before issuing requests.references/rest-calls.md for direct REST fallback patterns, auth setup, and safe request templates.Follow these steps in order when coding against Box.
who_am_i, completing client-provided OAuth if needed), then CLI (box users:get me --json), and record which are available. When tooling is missing, follow the escalation order from Route The Request (MCP setup → CLI setup → REST after explicit confirmation). If the task is building application code (adding SDK endpoints, webhook handlers), tooling availability is secondary — proceed to step 1.Read and follow
references/guardrails.mdin every session. It covers confirmation gates for destructive actions, hub modifications, file comments, Doc Gen output locations, externally shared folders, content display preferences, and Box AI governance.
references/ai-and-retrieval.md for the full preference order and fallback chain.references/bulk-operations.md.references/box-cli.md for details. For bulk work, default to CLI and use REST only after MCP/CLI setup attempts fail or the user explicitly confirms REST fallback.box configure:environments:get --current as a routine auth check — it can print sensitive environment details.box CLI commands when box is installed and authenticated.BOX_ACCESS_TOKEN) and safe auth handling before issuing requests.box users:get me --json.For example smoke-check commands, see references/box-cli.md (Common verification commands).
The final answer should include:
references/guardrails.md: mandatory safety and scope constraints for Box MCP tool usagereferences/content-workflows.md: files and folders — uploads, downloads, previews, folder trees, moves, metadata; MCP tools + CLI/REST patternsreferences/collaboration.md: sharing and access — collaborator roles, shared links, external-sharing rules; MCP tools + CLI/REST patternsreferences/mcp-search.md: finding content — keyword, folder-name, and metadata search via MCPreferences/ai-and-retrieval.md: Box AI and retrieval — Q&A, extraction, agents, content understanding preference order; MCP tools + CLI commandsreferences/mcp-hubs.md: Box Hubs — creation, item management, hub-level Q&A via MCPreferences/mcp-doc-gen.md: Box Doc Gen — template registration and document generation via MCPreferences/bulk-operations.md: organizing files at scale — batch moves, folder hierarchy creation, serial execution, and rate-limit handlingreferences/auth-and-setup.md: auth path selection, MCP server setup, SDK vs REST choice, existing-codebase inspection, and current Box doc anchorsreferences/box-cli.md: CLI-first local auth, smoke-test commands, and safe verification patternsreferences/rest-calls.md: direct REST fallback patterns, auth setup, and safe request templatesreferences/webhooks-and-events.md: webhook setup, event-feed usage, idempotency, and verificationreferences/workflows.md: quick workflow router when the task is ambiguousreferences/troubleshooting.md: common failure modes and a debugging checklist