Server Configuration

Configure authentication, CORS, request limits, and other security settings for your MCP server.

Configure authentication, CORS, request limits, and other security settings for your MCP server.

Creating a Server

// Get or create a server instance (singleton by name)
server = MCPServer( "myApp" )

// Multiple servers for different purposes
apiServer = MCPServer( "api" )
adminServer = MCPServer( "admin" )

Server Info

server = MCPServer( "myApp" )
    .setDescription( "My Application MCP Server" )
    .setVersion( "2.0.0" )

// Get server info
info = server.getServerInfo()
// { name: "myApp", version: "2.0.0", description: "..." }

Basic Authentication 🔒

Protect your server with HTTP Basic Authentication:

server = MCPServer( "myApp" )
    .withBasicAuth( "admin", "secretPassword123" )
    .registerTool( myTool )

How it works:

• Credentials verified before any request processing

• Returns 401 Unauthorized if invalid

• Uses standard HTTP Basic Authentication (base64-encoded username:password)

• Zero overhead when not configured

Making authenticated requests:

# Using curl with basic auth
curl -X POST http://localhost/~bxai/mcp.bxm?server=myApp \
  -u admin:secretPassword123 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'

Check if enabled:

if ( server.hasBasicAuth() ) {
    writeOutput( "This server requires authentication" )
}

Best Practices:

• ✅ Always use HTTPS in production

• ✅ Store passwords in environment variables

• ✅ Use strong, unique passwords

• ✅ Combine with CORS settings

• ✅ Log authentication failures

Example with environment variables:

MCPServer( "admin" )
    .withBasicAuth( getEnv( "MCP_ADMIN_USER" ), getEnv( "MCP_ADMIN_PASS" ) )
    .registerTool( adminTool )

CORS Configuration 🌐

Control which origins can access your server:

// Allow a single origin
server = MCPServer( "myApp" )
    .withCors( "https://example.com" )

// Allow multiple origins
server = MCPServer( "myApp" )
    .withCors( [ "https://example.com", "https://app.example.com" ] )

// Allow all origins (use with caution!)
server = MCPServer( "myApp" )
    .withCors( "*" )

// Wildcard subdomain matching
server = MCPServer( "myApp" )
    .withCors( [ "*.example.com", "https://trusted.org" ] )

Wildcard Patterns:

• *.example.com — Matches any subdomain

• * — Matches all origins

• Exact matches — Only specific origins

Dynamic Management:

server = MCPServer( "myApp" )
    .addCorsOrigin( "https://example.com" )
    .addCorsOrigin( "https://app.example.com" )

origins = server.getCorsAllowedOrigins()

if ( server.isCorsAllowed( "https://example.com" ) ) {
    writeOutput( "Origin is allowed" )
}

Security:

• ✅ Avoid * in production

• ✅ Use HTTPS origins

• ✅ Combine with authentication

• ✅ Review periodically

IP Allow Lists 🌍

Restrict access to specific client IPs and CIDR ranges.

// Allow only localhost + private subnet
server = MCPServer( "myApp" )
    .withAllowedIPs( [ "127.0.0.1", "192.168.1.0/24" ] )
    .registerTool( myTool )

// Add entries incrementally
server.addAllowedIP( "10.0.0.25" )
server.addAllowedIP( "10.0.1.0/24" )

// Remove all restrictions (allow all IPs)
server.clearAllowedIPs()

How it works:

• If no allow list is configured, all IPs are allowed

• Exact IP matches are supported (for example 203.0.113.10)

• CIDR ranges are supported (for example 203.0.113.0/24)

• Non-matching requests are rejected with 403 Forbidden

Request extraction order for client IP:

1. x-forwarded-for

2. cf-connecting-ip

3. true-client-ip

4. x-real-ip

5. Fallback to connection remote address

// Check if filtering is active
if ( server.hasAllowedIPs() ) {
    writeOutput( "IP filtering is enabled" )
}

Proxy deployment tip:

• Ensure your proxy/load balancer forwards the expected client IP headers

• Keep trusted proxy infrastructure under your control to avoid spoofed headers

Built-in BoxLang MCP server configuration:

// Module settings example
boxlangMCP: {
    enabled: true,
    authToken: "your-secret-token",
    allowedIPs: [ "127.0.0.1", "192.168.1.0/24" ],
    corsAllowedOrigins: [ "https://example.com" ]
}

Request Body Size Limits 📏

Protect against large payloads:

// Limit to 1MB
server = MCPServer( "myApp" )
    .withBodyLimit( 1048576 )

// Limit to 500KB
server = MCPServer( "myApp" )
    .withBodyLimit( 500 * 1024 )

// Unlimited (default: 0)
server = MCPServer( "myApp" )
    .withBodyLimit( 0 )

How it works:

• Checks body size before processing

• Returns 413 Payload Too Large if exceeded

• Default is 0 (unlimited)

• Applies to entire JSON-RPC request

Get current limit:

maxSize = server.getMaxRequestBodySize()

Use Cases:

• Public APIs — Prevent abuse

• Resource constraints — Match server limits

• Tool-specific limits — Different servers, different limits

• DoS prevention — Basic protection

Example — Tiered Limits:

// Public API - strict limits
MCPServer( "public" )
    .withBodyLimit( 100 * 1024 )  // 100KB
    .registerTool( publicTool )

// Internal API - generous limits
MCPServer( "internal" )
    .withBodyLimit( 10 * 1024 * 1024 )  // 10MB
    .withBasicAuth( "admin", "secret" )
    .registerTool( adminTool )

// Data import - unlimited
MCPServer( "import" )
    .withBodyLimit( 0 )
    .registerTool( importTool )

Custom API Key Validation 🔑

Implement custom authentication logic:

// Simple validation
server = MCPServer( "myApp" )
    .withApiKeyProvider( ( apiKey, requestData ) => {
        return apiKey == "my-secret-key-12345"
    } )

// Database lookup
server = MCPServer( "myApp" )
    .withApiKeyProvider( ( apiKey, requestData ) => {
        var user = userService.findByApiKey( apiKey )
        return !isNull( user ) && user.isActive
    } )

// Complex validation with rate limiting
server = MCPServer( "myApp" )
    .withApiKeyProvider( ( apiKey, requestData ) => {
        var key = apiKeyService.validate( apiKey )
        if ( isNull( key ) ) return false

        if ( rateLimiter.isExceeded( key.userId ) ) {
            throw( "Rate limit exceeded", "RateLimitError" )
        }

        auditLog.record( key.userId, requestData.method )
        return true
    } )

Provider Function Signature:

function apiKeyProvider(
    required string apiKey,
    required struct requestData
) {
    // Return true to allow, false to deny
    // Throw exception for errors
    return true
}

API Key Extraction: The server automatically extracts keys from:

1. X-API-Key header

2. Authorization: Bearer <token> header

Making requests:

# Using X-API-Key header
curl -X POST http://localhost/~bxai/mcp.bxm?server=myApp \
  -H "X-API-Key: my-secret-key-12345" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'

# Using Bearer token
curl -X POST http://localhost/~bxai/mcp.bxm?server=myApp \
  -H "Authorization: Bearer my-secret-key-12345" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'

Multi-Tenant Example:

MCPServer( "api" )
    .withApiKeyProvider( ( apiKey, requestData ) => {
        var tenant = tenantService.validateApiKey( apiKey )
        if ( isNull( tenant ) ) return false

        if ( !tenant.hasFeature( requestData.method ) ) {
            throw( "Feature not available in your plan", "AccessDenied" )
        }

        request.tenantId = tenant.id
        request.tenantName = tenant.name

        usageTracker.record(
            tenantId: tenant.id,
            method: requestData.method,
            timestamp: now()
        )

        return true
    } )
    .registerTool( myTool )

Combining Security Features

Use multiple layers together:

server = MCPServer( "enterprise" )
    // IP allow list - network-level filtering
    .withAllowedIPs( [ "10.10.0.0/16", "203.0.113.25" ] )
    // CORS - restrict origins
    .withCors( [ "https://app.example.com", "*.example.com" ] )
    // Body limits - prevent abuse
    .withBodyLimit( 1048576 )  // 1MB
    // API keys - identify clients
    .withApiKeyProvider( validateApiKey )
    // Basic auth - admin access
    .withBasicAuth( "admin", "secret" )
    // Tools
    .registerTool( toolOne )
    .registerTool( toolTwo )

Security Processing Order 🔐

When a request arrives, checks execute in this order:

1. Body Size Check — Reject oversized payloads first

2. IP Allow List Check — Reject disallowed client addresses

3. CORS Validation — Check origin header

4. Basic Authentication — Verify credentials

5. API Key Validation — Call custom provider

6. Request Processing — Only after all checks pass

Short-Circuit Behavior:

• Each layer can immediately reject the request

• Failed checks return error responses

• Security headers always included in responses

• Events fired for all security failures

• IP allow list failures return 403 Forbidden

Security Headers 🛡️

All HTTP responses automatically include industry-standard security headers:

Header	Value	Purpose
X-Content-Type-Options	nosniff	Prevents MIME type sniffing
X-Frame-Options	DENY	Blocks iframe embedding
X-XSS-Protection	1; mode=block	Enables XSS filtering
Referrer-Policy	strict-origin-when-cross-origin	Controls referrer leaking
Content-Security-Policy	default-src 'none'	Restricts resource loading
Strict-Transport-Security	max-age=31536000	Forces HTTPS (HTTPS only)
Permissions-Policy	Disables geo/mic/camera	Disables sensitive APIs

No configuration needed — Headers applied automatically!

Next Steps

• 🧩 Registering Tools — Add functionality

• 📋 Observability — Monitor requests

• 🏗️ Class-Based Servers — Organize complex servers

• ✅ Best Practices — Production setup