Box MCP Setup

Box MCP Setup

The cloud plugin requires Box's official remote MCP server at mcp.box.com. It's Box-maintained, OAuth 2.0, and exposes the ~50+ tools the plugin uses (files, search, Box AI, Hubs, Doc Gen, metadata).

The self-hosted Box MCP server (box/mcp-server-box) is deprecated by Box. Don't start new projects with it.

Setup walkthrough

Step 1 — Enable the Box MCP integration in Box Admin

1. Sign into Box as an admin
2. Go to Admin Console → Integrations (also called Apps & Integrations)
3. Find the "Box MCP server" predefined integration
4. Enable it
5. Note the Client ID and Client Secret it generates
6. Set the OAuth scopes: root_readwrite, ai.readwrite, docgen.readwrite
7. Set the redirect URI to your platform's MCP callback (Claude Code / Cowork handle this automatically when you use Settings → Connectors → Box)

Step 2 — Connect in your agent platform

Claude Code:

1. Settings → Connectors → Box → Add connection
2. OAuth flow: sign in as your Box user, grant the requested scopes
3. Done

Claude Cowork:

1. Personal settings → Connectors → Box → Add connection (per-user OAuth)
2. OR admin → Connectors → Box (for org-wide service-account auth via CCG)

Other agent platforms:

• Use Box's MCP URL https://mcp.box.com as your remote MCP endpoint
• Auth via OAuth 2.0 — see Authentication for per-platform guidance

Step 3 — Verify with the plugin

/box-mcp-check

Expects:

• Connected MCP: box-remote-mcp (official)
• Server URL: mcp.box.com
• Scopes granted: root_readwrite, ai.readwrite, docgen.readwrite
• Status: PASS
• Box AI tools available: yes
• Box Hubs support: yes (if Enterprise Plus or higher)

If any of these are missing, the skill surfaces the specific fix.

What if I've installed a community Box MCP?

Common community MCPs:

• hmk/box-mcp-server — works for basic file operations
• box/mcp-server-box — Box's own previously-self-hosted, now deprecated

The plugin's non-AI skills work with these (file write, recall via index files, etc.). But the AI-powered skills won't — box_ai_* tools aren't exposed.

To switch to the official MCP:

1. In your platform: disconnect the current Box MCP connection
2. Enable the "Box MCP server" predefined integration in Box Admin (as above)
3. Reconnect in your platform — the official MCP at mcp.box.com becomes the connected one
4. Run /box-mcp-check to verify

OAuth scopes — what each is for

Scope	Used by	Why
root_readwrite	All file/folder operations	The baseline plugin functionality
ai.readwrite	/box-ai-recall, /box-ai-extract, /box-ai-agent	Box AI calls
docgen.readwrite	(future — Doc Gen integration; not used in v0.1.0)	Future-proofs the connection
manage_enterprise_properties	/box-init on Business+ (creates boxMemory template)	Template create permission
manage_managed_users	(not used)	Admin user management

The plugin doesn't need manage_managed_users. The manage_enterprise_properties scope is only needed for template creation on Business+; without it, template-create fails and the plugin falls back to read-only on existing templates.

Troubleshooting

Symptom	Likely cause	Fix
/box-mcp-check says "not connected"	Box MCP integration not enabled in your platform	Settings → Connectors → Box
Status: DEGRADED	Wrong MCP variant (community or deprecated self-hosted)	Switch to official mcp.box.com per Step 2 above
403 on /box-ai-recall	ai.readwrite scope not granted	Disconnect + reconnect Box MCP; ensure scope grant during OAuth
403 on /box-init template create	manage_enterprise_properties not granted	Disconnect + reconnect with admin consent
Tools missing in tool inventory	Old / minimal MCP variant	Switch to official MCP

See also

• box-mcp-check — the verification skill
• Authentication — auth modes for non-Claude agents
• Troubleshooting — more diagnostic flows
• Box MCP overview
• Box remote MCP setup