Connect MCP Servers to the AI Content Assistant and the AI Perspective
This page describes how to connect external Model Context Protocol (MCP) servers to the AI Content Assistant and the AI perspective, so that authors can use the tools of those servers in their conversations in both.
Info: MCP server support is available from Bloomreach Content 17.4.
Introduction
The Model Context Protocol is an open standard for connecting AI assistants to external tools and data. An MCP server exposes a set of tools, for example "search the documentation" or "ask a question about a GitHub repository". The AI Content Assistant and the AI Perspective both act as MCP clients: you configure which servers they connect to, and during a conversation the assistant decides when to call their tools.
Typical uses:
-
Answer product questions from your documentation instead of from the model's general knowledge.
-
Look up information in code repositories, ticketing systems, or other internal services.
-
Combine external information with the assistant's content tools, for example to write a document based on documentation search results.
The AI Content Assistant and the AI Perspective share one MCP configuration: every server you connect is available in both. On this page, the assistant refers to either of them. The tools of the connected servers are used alongside the built-in content tools; the model chooses which tools to call.
Info: MCP tools require a model provider and model that support tool calling. From 17.4, Ollama supports tool calling, but the model must support tools. See Initialize and Configure via Properties.
How It Works
-
Connection on first use. The assistant connects to a server on the first chat turn that needs it, not when the CMS starts. A server that is down never prevents the CMS from starting.
-
Tool names. Every tool name gets the server ID as a prefix, for example
brxmdocs_search, so two servers can expose tools with the same name. -
Server descriptions. The assistant is told which servers are connected, together with the short description each server reports about itself. This helps the model to look questions within a server's topic up instead of answering from memory.
-
Unavailable servers. If a configured server cannot be reached, the assistant is told so, and tells the user that the server is unavailable instead of answering as if it had used it. The assistant retries the connection after 30 seconds.
-
Recovery. If a tool call fails, for example because the server was redeployed, the assistant reconnects on the next chat turn. A CMS restart is not needed.
-
Confirmation. As with the built-in tools, the assistant asks the user to confirm before it calls a tool that changes data.
Configure MCP Servers
You can configure MCP servers in the JCR repository, in properties files, or in a combination of both.
All Values Are Strings
Like the rest of the AI module configuration, every field is a single string value.
-
In YAML, quote values that would otherwise be read as a boolean or a number, for example
enabled: 'true'andtimeout: '30000'. An unquoted value becomes a typed property, which is ignored. A server with an unquotedenabled: trueis therefore disabled. -
List values (
argsandenv) are comma-separated, for exampleargs: '-y,@modelcontextprotocol/server-memory'.
Configure in the JCR Repository
Add one child node per server under /hippo:configuration/hippo:modules/ai-service/hippo:moduleconfig/mcp-servers. The node name is the server ID.
Warning: Each server node must be of type
hipposys:moduleconfig. Usingnt:unstructuredcauses aConstraintViolationExceptionduring bootstrap.
The mcp-servers node itself is created by the AI module, so your project only adds the server nodes. For example:
definitions: config: /hippo:configuration/hippo:modules/ai-service/hippo:moduleconfig/mcp-servers/brxmdocs: jcr:primaryType: hipposys:moduleconfig enabled: 'true' name: brXM Documentation transport: streamable-http url: https://example.com/mcp /hippo:configuration/hippo:modules/ai-service/hippo:moduleconfig/mcp-servers/deepwiki: jcr:primaryType: hipposys:moduleconfig enabled: 'true' name: DeepWiki transport: streamable-http url: https://mcp.deepwiki.com/mcp
Configure Using Properties Files
You can also define servers in xm-ai-service.properties, in platform.properties, as system properties, or as environment variables. See Initialize and Configure via Properties for where these files are located.
List the server IDs in brxm.ai.mcp.servers, then set each field as brxm.ai.mcp.servers.<serverId>.<field>:
brxm.ai.mcp.servers=brxmdocs,deepwiki brxm.ai.mcp.servers.brxmdocs.enabled=true brxm.ai.mcp.servers.brxmdocs.name=brXM Documentation brxm.ai.mcp.servers.brxmdocs.transport=streamable-http brxm.ai.mcp.servers.brxmdocs.url=https://example.com/mcp brxm.ai.mcp.servers.deepwiki.enabled=true brxm.ai.mcp.servers.deepwiki.name=DeepWiki brxm.ai.mcp.servers.deepwiki.url=https://mcp.deepwiki.com/mcp
Each property can also be set as an environment variable: write the name in upper case and replace dots with underscores. For example, brxm.ai.mcp.servers.brxmdocs.authToken becomes BRXM_AI_MCP_SERVERS_BRXMDOCS_AUTHTOKEN.
Combine JCR and Properties
The JCR configuration takes precedence, field by field:
-
If a field is set on the server node, that value is used.
-
If a field is not set on the node, the value of
brxm.ai.mcp.servers.<serverId>.<field>is used, if present. -
Servers listed in
brxm.ai.mcp.serversthat have no node in the JCR repository are configured entirely from properties. -
A server disabled in the JCR repository (
enabled: 'false') stays disabled, even if a property enables it.
This lets you keep the server definition in the JCR repository and provide only the token through an environment variable. See Authentication.
Server Properties
| Property | Required | Type | Description | Default | Example |
|---|---|---|---|---|---|
enabled | yes | boolean | Connects the server when true. Any other value disables it. | false | 'true' |
name | no | string | Display name of the server, used when the assistant refers to it. | the server ID | brXM Documentation |
transport | no | string | streamable-http, sse, or stdio. | streamable-http | sse |
url | yes for HTTP and SSE | url | Full URL of the MCP endpoint, including the path. | https://mcp.deepwiki.com/mcp | |
command | yes for STDIO | string | Command that starts the server process. | npx | |
args | no | comma-separated list | Arguments for command. | '-y,@modelcontextprotocol/server-memory' | |
env | no | comma-separated list | Additional environment variables for the server process, as KEY=value. | 'API_REGION=eu,LOG_LEVEL=warn' | |
timeout | no | integer (ms) | Maximum duration of a single request to the server, such as a tool call. | 30000 | '60000' |
handshakeTimeout | no | integer (ms) | Maximum duration of the initial connection to the server. Raise it for hosted servers with a slow handshake; keep it low for fast servers, so that an unreachable server fails quickly. | 10000 | '25000' |
authToken | no | string | Bearer token, sent as Authorization: Bearer <token>. | ||
authHeader | no | string | Custom header, in the format Name: value. | 'X-API-Key: abc123' |
Other properties on a server node are ignored. An invalid timeout or handshakeTimeout value falls back to the default.
Authentication
For HTTP and SSE servers, two authentication options are available. They can be combined.
-
authTokenadds the headerAuthorization: Bearer <token>to every request. -
authHeaderadds a custom header to every request, for exampleX-API-Key: abc123.
To keep tokens out of your bootstrap YAML, define the server in the JCR repository without a token and provide the token as an environment variable:
export BRXM_AI_MCP_SERVERS_BRXMDOCS_AUTHTOKEN=<token> export BRXM_AI_MCP_SERVERS_BRXMDOCS_AUTHHEADER='X-Account-Id: 1234'
A token set on the JCR node takes precedence over the environment variable. A node token is convenient for local development; for other environments, prefer environment variables.
For STDIO servers, pass credentials to the server process with env.
Info: Tokens and headers are never written to the logs.
Examples
Streamable HTTP Server With a Token
/hippo:configuration/hippo:modules/ai-service/hippo:moduleconfig/mcp-servers/internaldocs: jcr:primaryType: hipposys:moduleconfig enabled: 'true' name: Internal Documentation transport: streamable-http url: https://mcp.example.com/mcp handshakeTimeout: '20000'
export BRXM_AI_MCP_SERVERS_INTERNALDOCS_AUTHTOKEN=<token>
SSE Server With an API Key Header
brxm.ai.mcp.servers=tickets brxm.ai.mcp.servers.tickets.enabled=true brxm.ai.mcp.servers.tickets.name=Ticket System brxm.ai.mcp.servers.tickets.transport=sse brxm.ai.mcp.servers.tickets.url=https://tickets.example.com/sse brxm.ai.mcp.servers.tickets.authHeader=X-API-Key: <key>
STDIO Server
A STDIO server runs as a child process of the CMS. The command and its runtime, such as Node.js or Python, must be installed on the CMS host. The CMS logs a warning for each STDIO server at startup; for production, prefer the Streamable HTTP or SSE transport.
/hippo:configuration/hippo:modules/ai-service/hippo:moduleconfig/mcp-servers/memory: jcr:primaryType: hipposys:moduleconfig enabled: 'true' name: Notes transport: stdio command: npx args: '-y,@modelcontextprotocol/server-memory'
Warning: A STDIO server process inherits the environment of the CMS process, including environment variables that hold tokens for other MCP servers or model providers. Only configure STDIO commands that you trust as much as the CMS itself.
Verify the Configuration
At startup, the AI module logs which servers were found and which are enabled:
INFO main [ExternalMcpServerConfigLoader.loadEnabledServers:70] External MCP servers configured: [deepwiki, brxmdocs], enabled: [deepwiki, brxmdocs]
If a server is listed under configured but not under enabled, check that enabled is set to 'true' and that the value is quoted in YAML.
After startup, ask the assistant a question that falls within the topic of a server, or ask "Which tools can you use?". The connection is made on that first chat turn, which may take a little longer than usual.
Troubleshooting
| Symptom | Cause and solution |
|---|---|
| The server is not listed in the startup log | The node is not a child of mcp-servers, or the server ID is missing from brxm.ai.mcp.servers. |
| The server is listed as configured but not enabled | enabled is not the string true, for example an unquoted YAML boolean, or the server is disabled in the JCR repository. |
| The assistant says the server is unavailable | The server could not be reached within handshakeTimeout, or it rejected the credentials. Check the WARN messages in the CMS log. The assistant retries after 30 seconds. |
| The assistant answers from its general knowledge instead of using the server | Check that the model supports tool calling, and that the server reports a clear description of its topic. Mentioning the server in the question also helps. |
| Configuration changes have no effect | The MCP configuration is read at startup. Restart the CMS after changing it. |
Security Considerations
-
The assistant never sends conversation context, such as the user ID, the open document, or the user's message metadata, to MCP servers. Servers receive only the tool arguments chosen by the model.
-
Treat MCP servers as trusted integrations: the model sends them data from the conversation as tool arguments, and their responses become part of the conversation.
-
The description a server reports about itself is shortened to 300 characters before it is given to the model.
-
Server tokens are stored in the JCR repository at the same access level as the model provider API keys. Prefer environment variables for tokens outside local development.
Limitations
-
Configuration changes require a CMS restart.
-
The list of tools of a server is read when the assistant connects. If a server adds tools, they are available after the next reconnect or restart.
-
Authentication is static: OAuth flows and token refresh are not supported.
-
Tokens are shared by all CMS users; per-user credentials are not supported.