Whatever message this page gives is out now! Go check it out!
Server Initialization
Last update:
May 18, 2026
An MCP server in ColdFusion is a long-lived component that exposes tools, prompts, and resources to MCP clients (LLMs, agents, or other apps). Initializing it cleanly is critical for correctness and performance.
When to Initialize
Initialize the MCP server once per application lifecycle, not per request. Recommended places:
onApplicationStart()inApplication.cfc- A dedicated bootstrap CFC called from
onApplicationStart()
Avoid initializing in normal page requests (
.cfm) or per-session logic; that will lead to repeated setup work and inconsistent state. Defining a Server
A typical initialization pattern looks like this:
// Application.cfc (simplified)
component {
this.name = "MyMCPApp";
this.applicationTimeout = createTimeSpan(0, 2, 0, 0);
function onApplicationStart() {
initMcpServer();
return true;
}
private void function initMcpServer() {
// Define resources, prompts, tools, etc.
var resources = [
{
uri: "file:///var/app/logs/app.log",
name: "Application Logs",
mimeType: "text/plain"
}
];
application.mcpServer = mcpServerBuilder()
.serverInfo("my-server", "1.0.0")
.capabilities({
tools : true,
prompts : true,
resources : true
})
.tools([
{ cfc: "mcp.tools.HealthcheckTools" },
{ cfc: "mcp.tools.ReportingTools" }
])
.prompts([
{ name: "explain_error", template: "Explain this error: {{message}}" }
])
.resources(resources)
.cfcCaching(true)
.build();
}
}
Key points:
serverInfo(name, version): Provides a stable identity for your server. Keep this consistent across deployments unless you are intentionally versioning a breaking change.
capabilities(): Advertise only what you actually implement:
tools: trueif you exposetools/listandtools/callprompts: trueif you exposeprompts/list/prompts/getresources: trueif you exposeresources/list/resources/read
tools(): Register CFML components that implement MCP tools. Each CFC typically maps to one or more tool definitions. They should be:
- Pure functions (no hidden global state)
- Defensive about inputs (validate arguments)
- Fast, or explicitly annotated/logged if they can be slow
prompts(): Register named prompt templates that the client can fetch and render with parameters (e.g., explain-code, summarize-error).
resources(): Register read-only resources the server can expose. Ensure their location matches any root scoping you configure.
cfcCaching(true): Allows the runtime to cache instantiated tool CFCs, improving performance for repeated calls.
Error Handling During Initialization
Initialization failures should:
- Be logged with enough detail to debug (stack traces, environment info).
- Fail fast rather than partially initialize a broken server.
Example pattern:
private void function initMcpServer() {
try {
// ... as above
application.mcpServer = mcpServerBuilder()
// config...
.build();
} catch (any e) {
// Log and rethrow or mark application as unhealthy
writeLog(
file = "mcp",
type = "error",
text = "MCP server initialization failed: #e.message# #e.detail#"
);
// Optional: rethrow or set a flag
application.mcpServerInitError = e;
}
}
Clients should check for
application.mcpServer (or an error flag) before attempting to use the server.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
