Setting Up the AI MCP Server
The AI MCP Server (Model Context Protocol) acts as the bridge between the AI Service and the Universal Controller REST API. It exposes UC operations as tools that the AI can invoke during a conversation or analysis.
It is assumed you have already configured multiple Tomcat deployments and have a dedicated Tomcat instance ready for the AI MCP Server (for example, at tomcat/instances/ai-mcp).
To get started, follow the Installation Procedure below.
Installation Procedure
Deploy the WAR file
Copy the provided ai-mcp-{release}-{build}.war file into the webapps folder of your AI MCP Server Tomcat instance, as ai-mcp.war.
The {release} version must match the AI Service release; see Compatibility.
Configure base settings
Create a configuration file for the AI MCP Server. As with the AI Service, you can use a setenv.bat / setenv.sh file or an application.yml in the instance's conf folder.
A sample application.yml is given below. This file gives the minimal configurations needed to start the MCP Service.
Minimal configuration
logging:
file:
name: "${LOG_FILE_NAME:${LOG_DIR}/ai-mcp.log}"
threshold:
console: "${LOG_THRESHOLD_CONSOLE:OFF}"
logback:
rollingpolicy:
max-file-size: 10MB
max-history: 7
total-size-cap: 0B
clean-history-on-start: true
level:
com.stonebranch.ai: ${LOGGING_LEVEL_COM_STONEBRANCH_AI:INFO}
org.springframework: ${LOGGING_LEVEL_SPRING:INFO}
org.springframework.ai: ${LOGGING_LEVEL_SPRING_AI:${LOGGING_LEVEL_SPRING:INFO}}
stonebranch:
ai-mcp:
# MCP CORS Configuration
# SECURITY: For production, restrict to specific trusted origins
cors:
enabled: ${MCP_CORS_ENABLED:true}
# Production: specify exact origins like "https://your-app.com"
allowed-origins: "${MCP_CORS_ALLOWED_ORIGINS:http://localhost:*,http://127.0.0.1:*}"
# Example production config:
# allowed-origins: "https://your-app.com,https://trusted-partner.com"
# Default search time window settings for task instance list tools:
# list_task_instances_by_name, list_task_instances_by_task_name, list_task_instances_by_task_id
# Does NOT apply to workflow-scoped tools (list_task_instances_by_workflow_instance_*)
tools:
list-task-instances:
default-time-window: "${MCP_LIST_TASK_INSTANCES_DEFAULT_TIME_WINDOW:48h}" # Applied when AI does not specify timeWindow
max-time-window: "${MCP_LIST_TASK_INSTANCES_MAX_TIME_WINDOW:7d}" # Maximum allowed time window
default-limit: ${MCP_LIST_TASK_INSTANCES_DEFAULT_LIMIT:50} # Maximum number of results returned
# UC Remote API Configuration
# Specifies the Base URL(s) of the Universal Controller web application(s) for API calls.
#
# Single URL Configuration:
# In a single-node configuration or when using a load balancer, specify a single URL:
# scheme://hostname[:port]/contextpath
# Example: https://uc-server:8080/uc
#
# Multiple URL Configuration:
# Use this format to configure multiple UC instances or HA cluster nodes.
# Common use cases:
# - Multiple environments (DEV, QA, PROD)
# - HA cluster nodes with node-specific hostnames
#
# Format:
# cluster_node_id_1@scheme://hostname[:port]/contextpath|cluster_node_id_2@scheme://hostname[:port]/contextpath
#
# Example:
# ha1:8080-uc@https://ha1:8080/uc|ha2:8080-uc@https://ha2:8080/uc
#
# Routing:
# Single URL Configuration:
# The configured URL is used for all API calls regardless of the
# X-AI-UC-Service-Instance-Id header value.
#
# Multi-Node Configuration:
# The X-AI-UC-Service-Instance-Id header is required and must match a
# configured node ID exactly. If the header is missing or the node ID
# is not found in the configuration, an error is returned.
uc:
base-urls: "${UC_API_BASE_URLS:http://localhost:8080/uc}"
We recommend using these values (except for the options in the table below), unless you have a specific reason to change them. See Configuration for a full list of available options.
Set the following option with your own value, if needed:
| Environment Variable / Property | Description | Default |
|---|---|---|
MCP_SERVER_URL | URL of the AI MCP Server. | http://localhost:8082/ai-mcp |
You may also want to configure CORS for security.
Start the AI MCP Server
Start the Tomcat instance for the AI MCP Server. On Windows, run startup.bat from the instance's bin folder. On Linux, run startup.sh.
Check the logs in the instance's logs folder to verify a successful startup.
You can verify the service is running by accessing the actuator info endpoint: http://localhost:8082/ai-mcp/actuator/info. A healthy response will return JSON with the application name and version.
Once the AI and MCP services are running, the mandatory installation steps are complete, and you can proceed to Post-Installation. Optionally, you can configure a third-party MCP client such as Claude Code as well; see the advanced configuration section below.
Advanced / Optional Configuration
Connecting via MCP from a Third-party Client
The AI MCP Server endpoint is compatible with any MCP client that supports HTTP transport. The example below uses Claude Code.
Prerequisites
Before configuring your client, generate a Personal Access Token (PAT) in Universal Controller. This token authenticates your MCP requests against UC and is passed in the X-AI-UC-User-Callback-Token header. See Personal Access Tokens for instructions.
Claude Code Setup
The quickest way to register the server is with the claude mcp add command:
claude mcp add --transport http uc http://<mcp-hostname>:8082/ai-mcp/mcp \
--header "X-AI-Service-Type: UC" \
--header "X-AI-UC-User-Callback-Token: ucp_3Ege*****"
By default, this adds the server at local scope (current project only). Add --scope user to make it available in all your projects, or --scope project to share it with your team via a .mcp.json file at the repository root.
Alternatively, add the entry directly to ~/.claude.json (local/user scope) or .mcp.json (project scope):
{
"mcpServers": {
"uc": {
"type": "http",
"url": "http://<mcp-hostname>:8082/ai-mcp/mcp",
"headers": {
"X-AI-Service-Type": "UC",
"X-AI-UC-User-Callback-Token": "ucp_3Ege*****"
}
}
}
}
The "type": "http" field is required. An entry with a url but no type is treated as a stdio server and skipped.
Avoid committing your callback token, especially in a shared .mcp.json. Claude Code expands ${VAR} references in all string values, so you can write "X-AI-UC-User-Callback-Token": "${UC_CALLBACK_TOKEN}" and keep the actual token in your environment.
Multiple UC Cluster Nodes
If your MCP service is configured to communicate with multiple UC cluster nodes, add an X-AI-UC-Service-Instance-Id header specifying which node to route requests to:
{
"mcpServers": {
"uc": {
"type": "http",
"url": "http://<mcp-hostname>:8082/ai-mcp/mcp",
"headers": {
"X-AI-Service-Type": "UC",
"X-AI-UC-User-Callback-Token": "ucp_3Ege*****",
"X-AI-UC-Service-Instance-Id": "<uc-hostname>:8080-uc"
}
}
}
}
Or, using the CLI:
claude mcp add --transport http uc http://<mcp-hostname>:8082/ai-mcp/mcp \
--header "X-AI-Service-Type: UC" \
--header "X-AI-UC-User-Callback-Token: ucp_3Ege*****" \
--header "X-AI-UC-Service-Instance-Id: <uc-hostname>:8080-uc"
Verifying the Connection
Restart Claude Code after making configuration changes, then run:
claude mcp list
Your uc server should appear with a connected status. Inside a session, /mcp shows the server's status and available tools.
Removing the Server
To remove the server, run:
claude mcp remove uc
If the server was added at a specific scope, pass it explicitly (for example, claude mcp remove --scope project uc). Alternatively, delete the "uc" entry from the mcpServers object in the configuration file directly. The change takes effect on the next Claude Code session.