MCPClient

Last update:

May 18, 2026

Creates one or more MCP client instances from a configuration struct. Returns an mcpClient object or an array of mcpClient objects depending on the arguments passed.

Description

Create one or more MCP client instances from a configuration struct. For example, if configFile is passed and the configFile had multiple server configs, the method returns an array.

Syntax

MCPClient(configStruct)

History

New in ColdFusion 2025.0.08

Parameters: single server

Single server configuration struct fields
Field	Data type	Required	Description
`transport`	Struct	Yes	Describes how the client reaches one MCP server. HTTP transport: Use this when the MCP server is exposed over HTTP/streamable HTTP.

transport = {

  type = "http",

  url = "https://remote.mcpservers.org/fetch/mcp"

}

type: must be "http" for HTTP-based servers.
url: full URL to the MCP endpoint (e.g. /mcp, /mcp/call, /fetch/mcp), as shown in spec examples.

stdio transport: Use this when the MCP server runs as a local process (Node/Python/Java/CF):

transport = {

  type : "stdio",

  command : "/usr/local/bin/node",

  args : [ "/path/to/server.js" ],

  env = { apiKey : "skxxx" } // optional, server-specific

};

`type`: `"stdio"` for subprocess-based servers. `command`: executable to run (e.g. `node`, `python`, `java`). `args`: arguments array, typically including the MCP server script or jar. `env`: (optional) map of environment variables the MCP server needs (API keys, hosts, tokens).
`clientInfo`	Struct	No	Identifies your MCP client to the server during initialization.

clientInfo = {

  name = "weather-MCP-Client",

  version = "1.0.0"

};

`name`: descriptive, helps the server/logs identify the client (e.g. `"CF Jira Client"`). `version`: version string for your client (semantic versioning is good practice).
`capabilities`	Struct	No	Tells the server which optional MCP features the client supports and intends to use.

capabilities = {

  sampling : true,

  roots : true,

  elicitation : false

};

`sampling` — whether the client supports MCP sampling (asking an LLM to generate intermediate completions). `roots` — whether the client will provide resource roots (URIs that scope resources). `elicitation` — whether the client supports interactive elicitation workflows.
`initializationTimeout`	Numeric	No	Maximum time to wait for the MCP to initialize handshake. (default: 10, max: 3600).

initializationTimeout : 10; // seconds


`requestTimeout`	Numeric	No	Max time to wait for tool/resource/prompts calls. (default: 30, max: 3600).

requestTimeout : 10; // seconds


`loggingConsumer`	Function	No	Receives structured log events emitted by the MCP server. This is the primary hook for centralized logging of MCP server activity, debugging tool calls and resource reads, and building observability pipelines.

function loggingConsumer(any messages) { ... }

Whenever the server sends logs to the client, for example, on tool calls, errors, or general server events. This is especially useful in production to debug tool behavior without accessing server logs directly.
`samplingConsumer`	Function	No	Receives events related to sampling, when the MCP client/server interacts with an LLM to generate intermediate completions or sampling-based operations. This is useful when you want to inspect intermediate prompts, log or audit how sampling is used.

function samplingConsumer(array messages) { ... }

`messages` is typically an array of sampling message objects, often including: Role (`"assistant"`, `"system"`, etc.). Content (text, tool call suggestions, etc.). Metadata (timestamps, IDs).
`elicitationConsumer`	Function	No	Handles elicitation events, interactive flows where the server requests additional input or clarifications (e.g., the system needs more user info to proceed). This is where you might present follow-up questions in a UI, capture additional form fields or user responses, and decide whether to continue or abort a workflow.

function elicitationConsumer(array messages) { ... }

Like `samplingConsumer`, `messages` is an array of elicitation messages (questions, prompts for input, etc.).
`toolsChangeConsumer`	Function	No	Notified when the available tools change for that MCP client. This can happen if the MCP server hot-loads new tools, some tools are disabled/enabled at runtime, or a multi-tenant configuration changes your client's context.

function toolsChangeConsumer(array tools) { ... }

Parameters: multiple servers

When you want one ColdFusion app to talk to multiple MCP servers at once, you can still use MCPClient(configData). The key difference from the single-server case is that your configData now references a config file that describes multiple servers, and MCPClient will return one client per server.

Multiple server configuration struct fields
Field	Data type	Required	Description
`configFile`	String	Yes	A file path (string) pointing to a JSON configuration file (for example, `mcpServers.json`). The JSON file describes one or more MCP servers, each with its own transport settings (`type`, `url` / `command` / `args` / `env`).
`clientInfo`	Struct	No	When you use multiple MCP servers via `MCPClient(configData)` with a `configFile`, the `clientInfo` field in `configData` is a shared identity that is applied to each MCP client created from that config.

clientInfo = {

  name = "Healthcare-mcpclient",

  version = "1.0.0"

};


`capabilities`	Struct	No	When you configure multiple MCP servers via `MCPClient(configData)` with a `configFile`, the `capabilities` field in `configData` is a shared capabilities descriptor that applies to every MCP client created from that config.

capabilities = {

  sampling : true,

  roots : true,

  elicitation : false

};

`sampling`: client supports MCP sampling callbacks (LLM-assisted sampling). `roots`: client understands and will provide roots to scope resources. `elicitation`: client participates in elicitation (interactive ask-for-more-info flows).
`initializationTimeout`	Numeric	No	Same as that of a single MCP server.
`requestTimeout`	Numeric	No	Same as that of a single MCP server.
`loggingConsumer`	Function	No	Same as that of a single MCP server.
`samplingConsumer`	Function	No	Same as that of a single MCP server.
`elicitationConsumer`	Function	No	Same as that of a single MCP server.

Example: single server

<cfscript>

  transportConfig = {

    "type" = "http",

    "url" = "https://remote.mcpservers.org/fetch/mcp"

  };

  clientInfo = {

    "name" : "cf-mcp-client",

    "version" : "1.0.0"

  };

  capabilities = {

    "sampling" : true,

    "roots" : true,

    "elicitation" : true

  };

  configData = {

    "transport": transportConfig,

    "clientInfo": clientInfo,

    "capabilities": capabilities,

    "initializationTimeout": 10,

    "requestTimeout": 10,

    samplingConsumer: function(messages) {

      writeLog(file = "MCP_SAMPLING", text = serializeJSON(messages));

    },

    elicitationConsumer: function(messages) {

      writeLog(file = "MCP_ELICITATION", text = serializeJSON(messages));

    },

    loggingConsumer: function(logEvent) {

      var payload = structKeyExists(logEvent, "data") ? logEvent.data : logEvent;

      writeLog(file = "MCP_LOGS", text = serializeJSON(payload));

    },

    toolsChangeConsumer: function(tools) {

      application.mcpToolsCache = tools;

      writeLog(file = "MCP_CHANGES", text = "Tools changed: " & arrayLen(tools));

    }

  };

  clients = MCPClient(configData);

  mcpClient = clients[1];

</cfscript>

Example: multiple servers

<cfscript>

  var configData = {

    // Multi-server JSON descriptor

    configFile: getDirectoryFromPath(getCurrentTemplatePath()) & "mcpServers.json",

    // Shared client identity for all MCP servers in the file

    clientInfo: {

      name : "Healthcare-mcp-client",

      version : "1.0.0"

    },

    // Shared capabilities

    capabilities: {

      sampling : true,

      roots : true,

      elicitation : false

    },

    // Shared timeouts

    initializationTimeout : 50,

    requestTimeout : 50,

    // Optional shared consumers

    samplingConsumer: function(messages) {

      writeLog(file = "MCP_SAMPLING", text = serializeJSON(messages));

    },

    elicitationConsumer: function(messages) {

      application.lastElicitation = messages;

      writeLog(file = "MCP_ELICITATION", text = serializeJSON(messages));

    },

    loggingConsumer: function(logEvent) {

      var payload = structKeyExists(logEvent, "data") ? logEvent.data : logEvent;

      writeLog(file = "MCP_LOGS", text = "MCP log: " & serializeJSON(payload));

    },

    toolsChangeConsumer: function(tools) {

      writeLog(file = "MCP_CHANGES",

        text = "Tools changed. Count: " & arrayLen(tools));

    },

    resourcesChangeConsumer: function(resources) {

      writeLog(file = "MCP_CHANGES",

        text = "Resources changed. Count: " & arrayLen(resources));

    }

  };

  // Create one client per server defined in mcpServers.json

  var clients = MCPClient(configData);

  application.mcpClients = clients; // store for later use

</cfscript>

Was this page helpful?

We're glad. Tell us how this page helped.

Found the answer to my problem Understood the instructions Liked the feature

Other suggestions

We're sorry. Can you tell us what didn't work for you?

Didn't find the answer to my problem Couldn't understand the instructions Didn't like the feature

Other suggestions

Thank you for your feedback. Your response will help improve this page.

Was this helpful?

We are sorry the content didn't meet your needs.

Share additional feedback to help us improve.

0/255 | Character limit exceeded.

Thank you so much for sharing your feedback!