AI Routing

ColdBox provides first-class AI routing via toAi() and toMCP(), enabling automatic registration of AI inference and Model Context Protocol endpoints.

AI Routing requires BoxLang and the bx-ai module. It is not available on CFML engines.

ColdBox 8.1 introduces two powerful routing terminators for building AI-powered HTTP APIs:

• toAi() — Registers four standard AI inference endpoints (invoke, stream, batch, info) for any IAiRunnable object

• toMCP() — Registers a Model Context Protocol (MCP) server endpoint handled by MCPRequestProcessor

Both terminators behave like the resources() terminator: a single declaration expands to multiple concrete routes and all shared route modifiers (.as(), .withModule(), .withDomain(), etc.) are inherited by every generated sub-route.

---

toAi()

Overview

route( "/api/assistant" ).toAi( "models.AssistantAgent" );

A single toAi() call registers four routes automatically:

HTTP Verb	Pattern	Handler Action	Purpose
POST	/api/assistant/invoke	invoke	Synchronous single-turn inference
POST	/api/assistant/stream	stream	Server-Sent Events (SSE) streaming output
POST	/api/assistant/batch	batch	Batch / multi-turn inference
GET	/api/assistant/info	info	Metadata — model name, capabilities, etc.

Arguments

route( pattern ).toAi( target, [name] )

Argument	Type	Description
target	string or object	A WireBox mapping string or a live object instance that implements IAiRunnable
name	string	Optional base name for the generated routes. Defaults to the route pattern.

Basic Example

// config/Router.bx
function configure(){

    // Register a single AI agent — four endpoints created automatically
    route( "/api/chat" ).toAi( "models.ChatAgent" );

}

This produces the following routes:

POST /api/chat/invoke  → models.ChatAgent::invoke()
POST /api/chat/stream  → models.ChatAgent::stream()
POST /api/chat/batch   → models.ChatAgent::batch()
GET  /api/chat/info    → models.ChatAgent::info()

Modifier Inheritance

All standard route modifiers are inherited by every sub-route generated by toAi():

route( "/api/chat" )
    .withModule( "myModule" )
    .withDomain( "api.myapp.com" )
    .toAi( "models.ChatAgent" );

Invoke Endpoint

The invoke action handles a standard synchronous request/response cycle.

Request body (JSON):

{
  "prompt": "Summarize this document",
  "context": { "documentId": 42 }
}

Response (JSON):

{
  "response": "This document covers...",
  "model": "gpt-4o",
  "tokens": 128
}

Stream Endpoint

The stream action returns a Server-Sent Events (SSE) stream. The client should set Accept: text/event-stream.

Request body (JSON):

{
  "prompt": "Write a haiku about coding"
}

SSE Response:

data: {"token": "Code"}
data: {"token": " flows"}
data: {"token": " like water"}
data: [DONE]

Batch Endpoint

The batch action accepts an array of prompts and returns an array of responses in the same order.

Request body (JSON):

{
  "prompts": [
    "Translate: Hello",
    "Translate: Goodbye"
  ]
}

Response (JSON):

{
  "responses": [
    { "response": "Hola", "model": "gpt-4o" },
    { "response": "Adiós", "model": "gpt-4o" }
  ]
}

Info Endpoint

The info action (GET) returns metadata about the AI runnable — model name, version, available capabilities, etc.

Response (JSON):

{
  "model":    "gpt-4o",
  "provider": "openai",
  "capabilities": ["invoke", "stream", "batch"]
}

IAiRunnable Interface

Your agent class must implement coldbox.system.web.routing.IAiRunnable (or satisfy its duck-typed interface on BoxLang). The expected methods are:

// models/ChatAgent.bx
class implements="coldbox.system.web.routing.IAiRunnable" {

    function invoke( event, rc, prc ){}
    function stream( event, rc, prc ){}
    function batch( event, rc, prc ){}
    function info( event, rc, prc ){}

}

---

toMCP()

Overview

toMCP() registers a Model Context Protocol server endpoint. MCP is an open standard that allows AI models to interact with external tools, data sources, and services via a uniform API.

route( "/mcp/:mcpServer" ).toMCP();

Arguments

route( pattern ).toMCP( [name] )

Argument	Type	Description
name	string	Optional route name. Defaults to the route pattern.

The actual MCP server to execute is resolved from the URL pattern. You can define either a static name or use the :mcpServer placeholder to select the server dynamically from the URL.

Static Server

// Always routes to the "myServer" MCP server
route( "/mcp/assistant" ).toMCP( "myServer" );

Dynamic Server (Recommended)

Use the :mcpServer placeholder in your pattern to allow the URL to identify which MCP server to invoke:

// /mcp/codeReviewer  →  MCPRequestProcessor dispatching to "codeReviewer"
// /mcp/dataAnalyst   →  MCPRequestProcessor dispatching to "dataAnalyst"
route( "/mcp/:mcpServer" ).toMCP();

Modifier Inheritance

Like toAi(), all modifiers are inherited:

route( "/mcp/:mcpServer" )
    .withSSL()
    .withDomain( "mcp.myapp.com" )
    .toMCP();

MCP Server Registration

MCP servers are registered via WireBox or the ColdBox configuration. Refer to the BoxLang AI documentation and the Agentic ColdBox guide for details on building and registering MCP servers.

---

Using Both Together

// config/Router.bx
function configure(){

    // AI inference for a specific assistant
    route( "/api/v1/chat" )
        .withSSL()
        .toAi( "models.ChatAgent" );

    // MCP server hub — any registered MCP server accessible via URL
    route( "/mcp/:mcpServer" )
        .withSSL()
        .toMCP();

}