Authentication Guide

November 3, 2025 · View on GitHub

The Box MCP Server supports multiple authentication configurations to accommodate different deployment scenarios and security requirements. Authentication is controlled by two independent parameters:

--mcp-auth-type: Controls authentication between the MCP client and the MCP server
--box-auth-type: Controls authentication between the MCP server and the Box API

Command Line Options

usage: mcp_server_box.py [-h] [--transport {stdio,sse,http}] [--host HOST] [--port PORT]
                         [--mcp-auth-type {oauth,token,none}]
                         [--box-auth-type {oauth,ccg,jwt,mcp_client}]

options:
  --transport {stdio,sse,http}
                        Transport type (default: stdio)
  --host HOST           Host for SSE/HTTP transport (default: localhost)
  --port PORT           Port for SSE/HTTP transport (default: 8005)
  --mcp-auth-type {oauth,token,none}
                        Authentication type for MCP server (default: token)
  --box-auth-type {oauth,ccg,jwt,mcp_client}
                        Authentication type for Box API (default: oauth)

MCP Authentication Types

`oauth`

Uses the MCP client OAuth protocol
Implements partial Dynamic Client Registration
Can accept specific client ID and client secret credentials configured on the MCP client
Must be used with --box-auth-type=mcp_client
Box authentication is delegated to the MCP client

`token`

API key style authentication for the MCP server
Configure an access token that the MCP server validates against incoming requests
Independent of Box API authentication
Requires server-side Box authentication (oauth, ccg, or jwt)
Cannot be used with --box-auth-type=mcp_client

`none`

No authentication validation between MCP client and server
Assumes all requests from the MCP client are valid
Independent of Box API authentication
Most flexible - works with all Box authentication types
Note: stdio transport forces the usage of none

Box Authentication Types

The Box API always requires authentication. The MCP server supports multiple Box authentication methods:

`oauth`

Standard Box OAuth 2.0 user authentication
Opens browser for user authorization
Requires a Box Custom App with OAuth 2.0 enabled
Authenticates as the user who authorizes the application
Maintains user's Box security context
Requires Box OAuth client ID and client secret configuration

`ccg` (Client Credentials Grant)

Server-side authentication using Client Credentials Grant
Requires a Box Custom App with CCG enabled
Authenticates as a Service Account or specific user
Requires Box admin to enable the application
Requires Box client ID, client secret, and enterprise ID
Ideal for service account scenarios

`jwt` (JSON Web Token)

Server-side authentication using JWT
Requires a Box JWT App with public/private key pair
Uses the JSON config file downloaded from Box Developer Console
Authenticates as the Service Account
Requires Box admin to enable the application
Can act on behalf of other users if configured

`mcp_client`

Delegates Box authentication to the MCP client
The MCP server creates a BoxClient object using credentials provided by the client
With mcp-auth-type=oauth: MCP client configures Box OAuth during the MCP OAuth flow
With mcp-auth-type=none: MCP client must send a valid Box API Bearer token in the Authorization header
Useful when the MCP client handles Box authorization (developer token, OAuth, CCG, or JWT)

Dynamic Client Registration (Partial Implementation)

When using --mcp-auth-type=oauth with --box-auth-type=mcp_client, the MCP server implements a partial version of Dynamic Client Registration to enable the MCP OAuth flow with Box authentication.

Why Partial Implementation?

Box API does not natively support Dynamic Client Registration. To work around this limitation, the MCP server simulates the registration endpoint internally.

How It Works

Registration Endpoint: The MCP server exposes a registration endpoint that the MCP client calls during the OAuth flow
Static Credentials: The endpoint always returns the same client_id and client_secret configured in your .env file (e.g., .env.oauth)
Pre-configured Box App: You must create and configure a Box OAuth application in advance through the Box Developer Console

Important Limitations

Callback URLs Must Be Pre-Registered

Dynamic callback URLs are NOT supported. You must manually pre-register all callback/redirect URIs in your Box application configuration:

Go to the Box Developer Console
Select your OAuth application
Navigate to "Configuration" → "OAuth 2.0 Redirect URI"
Add all callback URLs that will be used. Common examples include:
- https://claude.ai/api/mcp/auth_callback (for Claude)
- https://claude.com/api/mcp/auth_callback (for Claude future use)
- http://localhost:6274/oauth/callback (for MCP Inspector)
- http://localhost:6274/oauth/callback/debug (for MCP Inspector)
- https://vscode.dev/redirect (for VS Code)
Save the configuration

Note: If the MCP client attempts to use a callback URL that is not pre-registered in the Box application, the OAuth flow will fail with an error from Box.

Configuration Requirements

For this to work, your .env file must contain:

BOX_CLIENT_ID = your_box_client_id
BOX_CLIENT_SECRET = your_box_client_secret
BOX_REDIRECT_URL = http://localhost:8000/callback  # Must match Box app configuration

# Optional: MCP server token authentication
BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

# Optional: Logging
LOG_LEVEL = DEBUG

The BOX_REDIRECT_URL must be one of the redirect URIs configured in your Box application.

Compatibility Matrix

mcp-auth-type	box-auth-type	Valid	Notes
oauth	oauth	❌	Not supported
oauth	ccg	❌	Not supported
oauth	jwt	❌	Not supported
oauth	mcp_client	✅	Recommended for Claude Desktop. Supports sending client ID and client secret configurations in MCP client. Partial support of Dynamic Client Registration
token	oauth	✅	MCP token auth + Box OAuth
token	ccg	✅	MCP token auth + Box CCG
token	jwt	✅	MCP token auth + Box JWT
token	mcp_client	❌	Not supported - token requires server-side Box auth
none	oauth	✅	No MCP auth + Box OAuth
none	ccg	✅	No MCP auth + Box CCG. Common for development
none	jwt	✅	No MCP auth + Box JWT. Common for development
none	mcp_client	✅	No MCP auth. Requires Box API valid Bearer token sent in Authorization header

Use Cases and Recommendations

Claude Desktop (Local Development)

Recommended Configuration (Remote Transport):

--transport=http --mcp-auth-type=oauth --box-auth-type=mcp_client
# or
--transport=sse --mcp-auth-type=oauth --box-auth-type=mcp_client

Best user experience with OAuth flow
MCP client handles Box OAuth configuration
Requires remote transport (HTTP or SSE) - does not work with stdio

Alternative Configuration (stdio Transport):

--transport=stdio --mcp-auth-type=none --box-auth-type=oauth

Uses stdio transport (forces mcp-auth-type=none)
Server handles Box OAuth authentication
Note: stdio transport is incompatible with mcp-auth-type=oauth

Development and Testing

Quick Testing (avoiding OAuth flow):

--mcp-auth-type=none --box-auth-type=ccg
# or
--mcp-auth-type=none --box-auth-type=jwt

No MCP authentication overhead
Uses service account credentials
Note: CCG and JWT require Box admin to enable the application

Testing with User Context:

--mcp-auth-type=none --box-auth-type=oauth

Maintains user's Box security context
Requires browser-based OAuth flow

Production Deployment

Production deployments should consider:

Transport: Remote deployment (HTTP/SSE) is recommended
User Security Context: Whether users should have their normal Box permissions
Authentication Security: Level of authentication required between client and server

User-Context Authentication (Recommended for multi-user scenarios)

Configuration:

--transport=http --mcp-auth-type=token --box-auth-type=oauth

Each user authenticates with their Box account
Maintains individual user security contexts
MCP server validates client access tokens
Users can only access Box content they have permissions for

Service Account Authentication (For specialized agents)

Configuration:

--transport=http --mcp-auth-type=token --box-auth-type=ccg
# or
--transport=http --mcp-auth-type=token --box-auth-type=jwt

Uses a service account with elevated permissions
Can access Box documents that transcend user security context
Ideal for specialized agents that need broad access
MCP token provides security between client and server
Requires Box admin to enable the application

Open Access with Client-Provided Box Auth

Configuration:

--transport=http --mcp-auth-type=none --box-auth-type=mcp_client

MCP client handles all Box authentication
Client sends Box Bearer token in Authorization header
Flexible for various Box auth methods (developer token, OAuth, CCG, JWT)
No authentication between MCP client and server

Configuration Files and Environment Variables

Environment Variables

Create a .env file in the project root with the appropriate configuration for your chosen authentication method.

For Box OAuth (`box-auth-type=oauth`)

Example: .env

BOX_CLIENT_ID = your_box_client_id
BOX_CLIENT_SECRET = your_box_client_secret
BOX_REDIRECT_URL = http://localhost:8000/callback

# Optional: MCP server token authentication
BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

# Optional: Logging
LOG_LEVEL = DEBUG

For Box CCG (`box-auth-type=ccg`)

CCG supports both user and enterprise (service account) authentication using BOX_SUBJECT_TYPE and BOX_SUBJECT_ID.

Example: .env.ccg.user (Authenticate as a specific user)

BOX_CLIENT_ID = your_box_client_id
BOX_CLIENT_SECRET = your_box_client_secret
BOX_SUBJECT_TYPE = user
BOX_SUBJECT_ID = your_user_id

# Optional: MCP server token authentication
BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

# Optional: Logging
LOG_LEVEL = DEBUG

Example: .env.ccg.enterprise (Authenticate as service account)

BOX_CLIENT_ID = your_box_client_id
BOX_CLIENT_SECRET = your_box_client_secret
BOX_SUBJECT_TYPE = enterprise
BOX_SUBJECT_ID = your_enterprise_id

# Optional: MCP server token authentication
BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

# Optional: Logging
LOG_LEVEL = DEBUG

Configuration Notes:

BOX_SUBJECT_TYPE: Use user to authenticate as a specific Box user, or enterprise for service account
BOX_SUBJECT_ID:
- When BOX_SUBJECT_TYPE=user: Provide the Box user ID
- When BOX_SUBJECT_TYPE=enterprise: Provide the Box enterprise ID

For Box JWT (`box-auth-type=jwt`)

JWT supports both user and enterprise (service account) authentication using BOX_SUBJECT_TYPE and BOX_SUBJECT_ID.

Option 1: Using JWT Config File

Example: .env.jwt.from.file

BOX_SUBJECT_TYPE = user
BOX_SUBJECT_ID = your_user_id

BOX_JWT_CONFIG_FILE = .jwt.conf.json

# Optional: MCP server token authentication
BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

# Optional: Logging
LOG_LEVEL = DEBUG

Option 2: Using Environment Variables

Example: .env.jwt.from.environment

BOX_CLIENT_ID = your_box_client_id
BOX_CLIENT_SECRET = your_box_client_secret
BOX_PUBLIC_KEY_ID = your_public_key_id
BOX_PRIVATE_KEY = "-----BEGIN ENCRYPTED PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END ENCRYPTED PRIVATE KEY-----\n"
BOX_PRIVATE_KEY_PASSPHRASE = your_private_key_passphrase
BOX_SUBJECT_TYPE = user
BOX_SUBJECT_ID = your_user_id

# Optional: MCP server token authentication
BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

# Optional: Logging
LOG_LEVEL = DEBUG

Configuration Notes:

BOX_SUBJECT_TYPE: Use user to authenticate as a specific Box user, or enterprise for service account
BOX_SUBJECT_ID:
- When BOX_SUBJECT_TYPE=user: Provide the Box user ID
- When BOX_SUBJECT_TYPE=enterprise: Provide the Box enterprise ID
BOX_PRIVATE_KEY: Must be a quoted string with escaped newlines (\n)

For MCP Token Auth (`mcp-auth-type=token`)

The BOX_MCP_SERVER_AUTH_TOKEN variable is used across all Box authentication types when using --mcp-auth-type=token:

BOX_MCP_SERVER_AUTH_TOKEN = your_mcp_server_token

This token is used to authenticate the MCP client to the MCP server (independent of Box authentication).

Important Security Note: Generate a strong, cryptographically secure token with at least 256 bits of entropy. You can generate a secure token using one of these methods:

# Using OpenSSL (recommended)
openssl rand -base64 32

# Using Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Never use predictable values, dictionary words, or short tokens for production environments.

OAuth Protected Resource Configuration

When using --mcp-auth-type=oauth, you must configure an OAuth Protected Resource metadata file that describes your MCP server to OAuth clients. This file is referenced by the OAUTH_PROTECTED_RESOURCES_CONFIG_FILE environment variable.

Purpose:

The OAuth Protected Resource configuration file provides metadata about your MCP server as an OAuth-protected resource. This allows MCP clients to discover:

Which authorization servers can issue tokens for this resource
What authentication methods are supported
What scopes are available
Where to find documentation

Configuration:

Create a .oauth-protected-resource.json file in your project root with the following structure:

{
    "authorization_servers": [
        "http://localhost:8005"
    ],
    "bearer_methods_supported": [
        "header"
    ],
    "resource": "http://localhost:8005/mcp",
    "resource_documentation": "https://developer.box.com/",
    "scopes_supported": [
        "root_readonly",
        "root_readwrite",
        "manage_managed_users",
        "manage_app_users",
        "manage_groups",
        "manage_webhook",
        "manage_enterprise_properties",
        "manage_data_retention",
        "sign_requests.readwrite",
        "ai.readwrite",
        "manage_triggers"
    ]
}

Field Descriptions:

authorization_servers: Array of authorization server URLs that can issue access tokens for this resource
- Include your MCP server URL (e.g., http://localhost:8005)
- The MCP server will still get the information from https://account.box.com/.well-known/oauth-authorization-server and inject the registration end point.
bearer_methods_supported: Authentication methods supported by the resource
- "header": Bearer token sent in the Authorization header (standard for Box API)
resource: The URL of the MCP server endpoint
- Should match your server's base URL plus /mcp path for http transport and /sse/ for SSE transport.
- Example: http://localhost:8005/mcp
resource_documentation: URL to documentation for the resource
- Can point to Box Developer documentation or your own docs
scopes_supported: Array of Box API scopes that this resource supports
- List all Box OAuth scopes your application needs
- See Box OAuth Scopes Documentation for available scopes
- These can more restrictive than the Box application configuration

Environment Variable:

Reference this file in your .env:

OAUTH_PROTECTED_RESOURCES_CONFIG_FILE = .oauth-protected-resource.json

Important Notes:

This file is only required when using --mcp-auth-type=oauth
Update authorization_servers and resource URLs to match your deployment (localhost for development, your domain for production)
The scopes listed should match the scopes configured in your Box OAuth application
This configuration is part of the OAuth 2.0 Protected Resource Metadata specification

Box Application Setup

Creating a Box OAuth App:

Go to Box Developer Console
Create a new Custom App
Select "User Authentication (OAuth 2.0)"
Configure redirect URIs
Copy the client ID and client secret

Creating a Box CCG App:

Go to Box Developer Console
Create a new Custom App
Select "Server Authentication (Client Credentials Grant)"
Configure application scopes
Submit for admin authorization
Copy the client ID, client secret, and enterprise ID

Creating a Box JWT App:

Go to Box Developer Console
Create a new Custom App
Select "Server Authentication (with JWT)"
Generate a public/private key pair
Submit for admin authorization
Download the JSON configuration file
Store the configuration file securely

Security Best Practices

Never commit credentials to version control: Use .env files and add them to .gitignore
Rotate tokens regularly: Especially for production deployments
Use appropriate authentication for your use case:
- Personal use: oauth + mcp_client
- Development: none + ccg/jwt
- Production (user context): token + oauth
- Production (service account): token + ccg/jwt
Restrict Box application permissions: Only grant necessary scopes
Use HTTPS in production: For HTTP/SSE transports
Implement rate limiting: Especially for open deployments