MCP Clients

The BoxLang AI Module includes built-in support for the Model Context Protocol (MCP), a standardized way for AI applications to connect to external data sources and tools.

🎯 What is MCP?

Model Context Protocol is an open protocol that enables AI models to:

🏗️ MCP Client Architecture

Model Context Protocol is an open protocol that enables AI models to:

• 🔧 Access Tools: Execute functions on remote servers

• 📚 Read Resources: Access documents, databases, and external data

• 💬 Use Prompts: Leverage server-defined prompt templates

• 🔍 Discover Capabilities: Dynamically learn what a server offers

🚀 Basic Usage

// Create an MCP client
client = MCP( "http://localhost:3000" )

// Send a request to a tool
result = client.send( "searchDocs", {
    query: "BoxLang syntax",
    limit: 10
} )

// Check the response
if ( result.getSuccess() ) {
    writeOutput( result.getData() )
} else {
    writeOutput( "Error: " & result.getError() )
}

⚙️ Client Configuration

⏱️ Timeout Configuration

Set request timeout in milliseconds:

client = MCP( "http://localhost:3000" )
    .withTimeout( 5000 )  // 5 second timeout

Custom Headers

Add custom HTTP headers to requests:

client = MCP( "http://localhost:3000" )
    .withHeaders( {
        "X-API-Key": "your-api-key",
        "X-Custom-Header": "value"
    } )

Authentication

Bearer Token Authentication:

client = MCP( "http://localhost:3000" )
    .withBearerToken( "your-bearer-token" )

Basic Authentication:

client = MCP( "http://localhost:3000" )
    .withAuth( "username", "password" )

Callbacks

Register success and error callbacks:

client = MCP( "http://localhost:3000" )
    .onSuccess( ( response ) => {
        writeLog(
            type: "info",
            text: "MCP Success: #serializeJSON( response.getData() )#"
        )
    } )
    .onError( ( response ) => {
        writeLog(
            type: "error",
            text: "MCP Error [#response.getStatusCode()#]: #response.getError()#"
        )
    } )

Fluent Chaining

All configuration methods return this for fluent API:

client = MCP( "http://localhost:3000" )
    .withTimeout( 10000 )
    .withBearerToken( getSystemSetting( "MCP_TOKEN" ) )
    .withHeaders( { "X-Request-ID": createUUID() } )
    .onSuccess( logSuccess )
    .onError( logError )

Discovery Methods

List Tools

Discover available tools on the server:

tools = MCP( "http://localhost:3000" ).listTools()

if ( tools.getSuccess() ) {
    for ( tool in tools.getData() ) {
        writeOutput( "
            <div>
                <h3>#tool.name#</h3>
                <p>#tool.description#</p>
                <pre>#serializeJSON( tool.parameters )#</pre>
            </div>
        " )
    }
}

List Resources

Get available resources:

resources = MCP( "http://localhost:3000" ).listResources()

if ( resources.getSuccess() ) {
    for ( resource in resources.getData() ) {
        writeOutput( "Resource: #resource.uri# (#resource.type#)" )
    }
}

List Prompts

Discover prompt templates:

prompts = MCP( "http://localhost:3000" ).listPrompts()

if ( prompts.getSuccess() ) {
    for ( prompt in prompts.getData() ) {
        writeOutput( "Prompt: #prompt.name#" )
        writeOutput( "Args: #prompt.arguments.toList()#" )
    }
}

Get Capabilities

Check server capabilities:

capabilities = MCP( "http://localhost:3000" ).getCapabilities()

if ( capabilities.getSuccess() ) {
    caps = capabilities.getData()
    writeOutput( "Server: #caps.serverInfo.name# v#caps.serverInfo.version#" )
    writeOutput( "Supports Tools: #caps.capabilities.tools#" )
    writeOutput( "Supports Resources: #caps.capabilities.resources#" )
}

Execution Methods

Send Tool Request

Invoke a tool with arguments:

// Simple invocation
result = MCP( "http://localhost:3000" )
    .send( "calculateTax", {
        amount: 100.00,
        state: "CA"
    } )

// With configuration
result = MCP( "http://localhost:3000" )
    .withTimeout( 30000 )
    .withBearerToken( token )
    .send( "processPayment", {
        orderId: "12345",
        amount: 99.99
    } )

Read Resource

Access a resource by URI:

content = MCP( "http://localhost:3000" )
    .readResource( "docs://getting-started.md" )

if ( content.getSuccess() ) {
    markdown = content.getData().content
    writeOutput( markdown )
}

Get Prompt

Retrieve a prompt template with arguments:

prompt = MCP( "http://localhost:3000" )
    .getPrompt( "generateCode", {
        language: "java",
        description: "Sort an array of integers"
    } )

if ( prompt.getSuccess() ) {
    promptText = prompt.getData().messages[ 1 ].content
    // Use promptText with aiChat()
    code = aiChat( promptText )
}

Response Structure

All MCP methods return an MCPResponse object:

response = client.send( "tool", {} )

// Properties
success = response.getSuccess()       // Boolean
data = response.getData()            // Any (struct, array, string)
error = response.getError()          // String
statusCode = response.getStatusCode() // Numeric
headers = response.getHeaders()      // Struct

// Convert to struct
struct = response.toStruct()
// {
//     "success": true,
//     "data": { ... },
//     "error": "",
//     "statusCode": 200,
//     "headers": { ... }
// }

Error Handling

Network Errors

result = MCP( "http://invalid-host:9999" )
    .withTimeout( 1000 )
    .listTools()

if ( !result.getSuccess() ) {
    // Network error occurred
    writeOutput( "Connection failed: " & result.getError() )
    // statusCode will be 0 for network errors
}

HTTP Errors

result = MCP( "http://localhost:3000" )
    .send( "unknownTool", {} )

if ( !result.getSuccess() ) {
    // HTTP error (4xx, 5xx)
    writeOutput( "HTTP #result.getStatusCode()#: #result.getError()#" )
}

Try-Catch Pattern

try {
    client = MCP( "http://localhost:3000" )
        .withTimeout( 5000 )

    result = client.send( "tool", { param: "value" } )

    if ( !result.getSuccess() ) {
        throw(
            type: "MCPError",
            message: result.getError(),
            detail: "Status: #result.getStatusCode()#"
        )
    }

    // Process successful result
    return result.getData()

} catch ( any e ) {
    writeLog(
        type: "error",
        text: "MCP operation failed: #e.message#"
    )
    rethrow
}

Real-World Examples

Documentation Search

// Search BoxLang documentation via MCP
function searchDocs( required string query, numeric limit = 10 ) {
    var client = MCP( "https://boxlang.ortusbooks.com/~gitbook/mcp" )
        .withTimeout( 10000 )
        .withBearerToken( getSystemSetting( "MCP_TOKEN" ) )

    var result = client.send( "search", {
        query: arguments.query,
        limit: arguments.limit,
        type: "documentation"
    } )

    if ( !result.getSuccess() ) {
        throw( "Search failed: " & result.getError() )
    }

    return result.getData().results
}

// Usage
docs = searchDocs( "BoxLang installation" )
for ( doc in docs ) {
    writeOutput( "<h3>#doc.title#</h3>" )
    writeOutput( "<p>#doc.excerpt#</p>" )
    writeOutput( "<a href='#doc.url#'>Read more</a>" )
}

Integration with AI Chat

// Use MCP tools with AI chat
function aiWithMCP( required string userMessage ) {
    // Get relevant docs via MCP
    var mcpClient = MCP( "http://localhost:3000" )
    var searchResult = mcpClient.send( "searchDocs", {
        query: arguments.userMessage
    } )

    if ( searchResult.getSuccess() ) {
        var docs = searchResult.getData().results
        var context = docs.map( d => d.content ).toList( chr(10) )

        // Use context with AI
        var response = aiChat( [
            aiMessage().system( "Answer using this context: #context#" ),
            aiMessage().user( arguments.userMessage )
        ] )

        return response
    }

    // Fallback without context
    return aiChat( arguments.userMessage )
}

// Usage
answer = aiWithMCP( "How do I install BoxLang?" )
writeOutput( answer )

Resource Caching

class {
    property name="mcpClient";
    property name="cache";

    function init() {
        variables.mcpClient = MCP( "http://localhost:3000" )
            .withTimeout( 30000 )
        variables.cache = {}
        return this
    }

    function getResource( required string uri ) {
        // Check cache
        if ( structKeyExists( variables.cache, arguments.uri ) ) {
            return variables.cache[ arguments.uri ]
        }

        // Fetch from MCP
        var result = variables.mcpClient.readResource( arguments.uri )

        if ( !result.getSuccess() ) {
            throw( "Failed to read resource: " & result.getError() )
        }

        // Cache and return
        variables.cache[ arguments.uri ] = result.getData()
        return result.getData()
    }
}

// Usage
resourceLoader = new ResourceLoader()
content = resourceLoader.getResource( "docs://api-reference.md" )

MCP Server Endpoints

The MCP client expects servers to implement these endpoints:

Endpoint	Method	Purpose	Request Body
/tools	GET	List available tools	None
/tools/{name}/invoke	POST	Invoke a tool	{ "params": {...} }
/resources	GET	List available resources	None
/resources/read	POST	Read a resource	{ "uri": "..." }
/prompts	GET	List available prompts	None
/prompts/{name}	POST	Get a prompt	{ "params": {...} }
/capabilities	GET	Get server capabilities	None

Stats & Observability 📊

Since BoxLang AI v3.2.0+

MCPClient now tracks internal usage and performance metrics via a MCPClientStats instance using atomic variables for thread safety.

Getting Stats

client = MCP( "http://localhost:3000" )

// Make some calls
tools = client.listTools()
result = client.callTool( "search", { query: "BoxLang" } )
resource = client.getResource( "config://app" )

// Get full stats
stats = client.getStats()
println( "Total calls: #stats.totalCalls#" )
println( "Success rate: #stats.successRate#%" )
println( "Avg response time: #stats.avgResponseTime#ms" )

// Per-tool breakdown
println( "Tool invocations: #serializeJSON( stats.byType.tool )#" )

// Lightweight summary
summary = client.getSummary()
println( "Summary: #serializeJSON( summary )#" )

Stats API

Method	Description
getStats()	Full stats struct with per-operation, per-tool, per-URI, per-prompt breakdowns
getSummary()	Lightweight summary with totalCalls, successRate, avgResponseTime, per-type totals, totalErrors, lastCallAt
resetStats()	Reset all counters to zero (fluent)

Stats Breakdown

Tracked operation types:

• tool — covers listTools + callTool

• resource — covers listResources + getResource

• prompt — covers listPrompts + getPrompt

• discovery — covers getCapabilities

Per-tool stats: count, totalTime, avgTime

Per-URI stats: resource read counts

Per-prompt stats: prompt generation counts

Events

Three new interception points fire from every HTTP call:

Event	When Fired
onMCPClientRequest	Before the HTTP request
onMCPClientResponse	On successful response
onMCPClientError	On HTTP errors or network exceptions

BoxRegisterInterceptor( "onMCPClientRequest", function( event ) {
    println( "MCP client #event.operation#: #event.name#" )
})

BoxRegisterInterceptor( "onMCPClientResponse", function( event ) {
    println( "Response in #event.executionTime#ms — status: #event.statusCode#" )
})

BoxRegisterInterceptor( "onMCPClientError", function( event ) {
    logError( "MCP client error: #event.operation#/#event.name# — #event.error#" )
})

Best Practices

1. Use Configuration Objects

// Create reusable client configurations
function createMCPClient( string env = "production" ) {
    var config = {
        "development": {
            url: "http://localhost:3000",
            timeout: 5000,
            token: ""
        },
        "production": {
            url: getSystemSetting( "MCP_URL" ),
            timeout: 30000,
            token: getSystemSetting( "MCP_TOKEN" )
        }
    }

    var settings = config[ arguments.env ]

    return MCP( settings.url )
        .withTimeout( settings.timeout )
        .withBearerToken( settings.token )
}

2. Always Check Success

// Never assume success
result = client.send( "tool", {} )

if ( result.getSuccess() ) {
    // Process data
    processData( result.getData() )
} else {
    // Handle error
    logError( result.getError() )
}

3. Use Callbacks for Observability

client = MCP( "http://localhost:3000" )
    .onSuccess( ( response ) => {
        writeLog(
            type: "info",
            text: "MCP request succeeded",
            extraInfo: {
                statusCode: response.getStatusCode(),
                dataSize: len( serializeJSON( response.getData() ) )
            }
        )
    } )
    .onError( ( response ) => {
        writeLog(
            type: "error",
            text: "MCP request failed: #response.getError()#",
            extraInfo: {
                statusCode: response.getStatusCode()
            }
        )
    } )

4. Timeout Appropriately

// Short timeout for quick operations
quickClient = MCP( url ).withTimeout( 2000 )

// Longer timeout for heavy operations
heavyClient = MCP( url ).withTimeout( 60000 )

5. Secure Credentials

// Never hardcode tokens
client = MCP( "http://localhost:3000" )
    .withBearerToken( getSystemSetting( "MCP_TOKEN" ) )

// Or use .env files
client = MCP( "http://localhost:3000" )
    .withBearerToken( server.system.environment.MCP_TOKEN )

Testing MCP Clients

Unit Testing

class extends="testbox.system.BaseSpec" {

    function run() {
        describe( "MCP Client", () => {

            it( "can create client", () => {
                var client = MCP( "http://localhost:3000" )
                expect( client ).toBeComponent()
                expect( client.getBaseURL() ).toBe( "http://localhost:3000" )
            } )

            it( "can configure timeout", () => {
                var client = MCP( "http://localhost:3000" )
                    .withTimeout( 5000 )
                expect( client.getTimeout() ).toBe( 5000 )
            } )

            it( "handles network errors", () => {
                var result = MCP( "http://invalid:9999" )
                    .withTimeout( 1000 )
                    .listTools()
                expect( result.getSuccess() ).toBeFalse()
                expect( result.getError() ).notToBeEmpty()
            } )

        } )
    }

}

Related Documentation

• BoxLang AI Module

• AI Tools

• AI Agents

External Resources

• Model Context Protocol Specification

• MCP Server Examples

• BoxLang Documentation MCP Server