SM-MCP settings

Overview

SM-MCP is the server component of the AI assistant chat. It receives questions from SA Web, calls a language model through SM-AI, and performs platform operations under the user's account. Its built-in operations are read-only.

Chats are stored in a dedicated history index. The service encrypts message content before writing it. The SM-MCP API checks a user's access to their chats.

For deployment requirements and the component connection order, see Installing the AI assistant.

Before installation

Prepare:

• the sm-mcp-<version>.tar.gz archive from the Search Anywhere Framework distribution
• the storage API address with scheme and port, and the cluster CA certificate
• an existing SM-MCP HTTPS certificate and key, or a CA key for issuing a certificate
• installed SM-AI, its address ending in /v1, and a model name from its registry
• a platform administrator account for uploading knowledge and skills and preparing and verifying history protection
• access to the configuration of every storage node and a maintenance window for restarting them one at a time
• a regular account with read access to the required data, .sm_mcp_knowledge, and .sm_agent_skills

The SM-MCP certificate must be trusted by the CA specified in opensearch.ssl.certificateAuthorities on Smart Monitor Web servers. The platform and SM-AI must be reachable from the SM-MCP server.

Installing the service

Extract the archive and run the installer:

tar -xzf sm-mcp-<version>.tar.gz
cd sm-mcp-<version>
sudo ./setup.sh install

During interactive installation, specify:

Group	Value
Chat API	Listening address and port, HTTPS settings
Platform	Storage API address and CA path
Model	SM-AI address ending in /v1 and its registry entry name
Knowledge and skills	Whether to upload and check the bundled corpus and skills
History	Whether to prepare the indexes, technical account, and encryption key
SA Web	Whether to write the SM-MCP address to cluster settings

Before making changes, the installer displays a summary and asks for confirmation. Enter the administrator password interactively. For the AI assistant to work, select knowledge and skill upload and validation, and history preparation.

The installer creates directories, installs the configuration and service, prepares an HTTPS certificate, and, if selected, adds the CA to the system trust store. This is needed to verify the SM-AI certificate.

You can provide parameters in an answers file:

cp example_config_sm-mcp.yaml answers.yaml
# Fill in answers.yaml before running the installer.
sudo ./setup.sh install -c answers.yaml

The administrator password is requested separately. Running setup.sh without a command opens a menu. --no-root prints privileged commands for an administrator to run; it is not a dry-run mode. Initial history preparation requires running commands as root.

By default, the chat API is available over HTTPS at 0.0.0.0:8088. Grant network access only to SA Web servers. HTTP is allowed only on the loopback address when both components are on the same server.

File locations

Path	Purpose
/app/sm-mcp/sm-mcp	Executable
/app/sm-mcp/config.yaml	Service configuration
/app/sm-mcp/ca-cert.pem	Cluster CA
/app/sm-mcp/corpus/, /app/sm-mcp/skills/	Bundled knowledge corpus and skills
/app/sm-mcp/tls/node.pem, node-key.pem	Chat API HTTPS certificate and key
/app/sm-mcp/keys/	History encryption keys
/etc/sm-mcp/history.env	Technical history account password
/etc/systemd/system/sm-mcp.service	systemd service
/etc/systemd/system/sm-mcp.service.d/history.conf	Connects the history password to the service after protection is verified

These are the paths used by the installer. The service runs as the opensearch user; the installer can create that user if it does not exist.

Configuration file

The installer creates /app/sm-mcp/config.yaml. Key parameters:

Parameter	Purpose
listen	Chat API address and port
tls.enabled	Chat API HTTPS; enabled by default
tls.certificate, tls.private_key	HTTPS certificate and key
opensearch.url, opensearch.ca_file	Storage API address and CA path
platform.version	Platform version
model.api_base	SM-AI address ending in /v1
model.name	SM-AI registry entry name
model.context_tokens	Context size; 0 uses model information from SM-AI
model.max_tokens	Maximum model response size
model.timeout	Timeout for one model request
model.stream	Stream the model response
runtime.default_tz	Default time zone; Europe/Moscow during installation
history.retention	Chat retention period; 720h (30 days) during installation
history.key_dir	History encryption key directory

Restart the service after changing settings:

sudo systemctl restart sm-mcp

The model name must match the name entry in the SM-AI registry. Choose the context size and response limit according to your model's capabilities.

Chat history

Installation prepares history if you select that step. The service starts saving chats only after index protection and a separate history enablement step.

1. Back up /app/sm-mcp/keys/ separately from cluster backups. Encrypted messages cannot be recovered without the key
2. On every storage node, add the following to opensearch.yml:

plugins.security.protected_indices.enabled: true
plugins.security.protected_indices.indices: [".sm_mcp_history*"]
plugins.security.protected_indices.roles: ["sm_mcp_history_runtime"]

If protection for other indexes is already configured, extend the existing lists without removing their values.

3. Restart all storage nodes one at a time
4. After the last node restarts, run from the installer directory:

sudo ./setup.sh enable-history

The command requests a platform administrator account and checks that writes to history are denied through the cluster nodes. The expected result is HTTP 403. History is not enabled if a write is possible.

If a node cannot be checked automatically through its published TLS address, interactive mode may request manual confirmation. Before confirming, verify its configuration and restart; do not assume protection based only on successful checks of other nodes.

After verification, the command connects the technical account password to the service and restarts SM-MCP. The history field in the /readyz response must be ok.

By default, a chat is retained for 30 days after its last message. history.retention: 0s disables time-based deletion. Back up the configuration, key directory, and history.env file, and restrict access to the backups. Do not make the keys publicly accessible: the service checks their owner and permissions.

Connecting SA Web

The installer can set the connection for all SA Web servers. If you skipped this step, run in the Dev Tools console:

PUT _cluster/settings
{
  "persistent": {
    "sme.mcp.enabled": true,
    "sme.mcp.service_url": "https://mcp.example.org",
    "sme.mcp.service_port": 8088,
    "sme.mcp.timeout": 600000
  }
}

Use the SM-MCP name from its certificate. Specify the address with a scheme and the port as a separate parameter.

Instead of cluster settings, you can set the address on each SA Web server in opensearch_dashboards.yml:

smart_monitor.ai.baseUrl: https://mcp.example.org:8088

Restart SA Web after changing the file. Cluster connection settings take precedence over smart_monitor.ai.baseUrl.

The SM-MCP certificate is verified against opensearch.ssl.certificateAuthorities in opensearch_dashboards.yml, including the service name match. You do not need to disable certificate verification for this connection.

Checking the service

Check the service and API from a SA Web or SM-MCP server:

sudo systemctl status sm-mcp
curl --cacert /app/sm-mcp/ca-cert.pem https://mcp.example.org:8088/healthz
curl --cacert /app/sm-mcp/ca-cert.pem -u '<login>' https://mcp.example.org:8088/readyz

Use the name from the certificate and a CA path available on that machine. For /readyz, use a regular account of a future chat user; curl prompts for the password.

/healthz returns {"status":"ok"}. In /readyz, check opensearch, model, and knowledge; after enabling history, also check history. The expected state is ok. The skills field may be unknown before the first chat request: the diagnostic request does not load the skill directory. Repeat the check after the first question.

Without an account, /readyz performs a limited check and does not confirm the user's access to knowledge and the model. Diagnostic responses do not replace asking a test question and checking chat history.

Situation	What to check
Service does not start	Configuration, TLS certificate and key paths, history key directory permissions
model: error	SM-AI address, access to /models with the user's account, model name, CA in the system trust store, and NO_PROXY
knowledge is not ready or skills remains unready after the first question	Corpus and skill uploads, the user's read permissions on their indexes
history is not ready	History preparation, protection on all nodes, and the enable-history result
SM-MCP works but chat is unavailable	Service address in platform or Web settings, network access, and certificate trust

View the service log:

sudo journalctl -u sm-mcp -o cat

Updating the service

Before updating, back up the configuration, history keys, and technical account password. Read the release notes for the version you received.

Extract the new distribution and run from its directory:

sudo ./setup.sh update

The installer replaces the binary, corpus, and skills. Configuration, indexes, and history keys are retained; previous files get a .prev suffix. An update may temporarily disable chat through sme.mcp.enabled and upload new knowledge and skills. Review the selected settings before confirming.

After the update, repeat the API check and ask a question in chat. Prepare history again only if the release notes require it.

Connecting external MCP clients

The /mcp route is available on the main SM-MCP port alongside the chat API. You can assign a separate address and port for external clients, exposing only /mcp and /healthz. The additional port is disabled by default.

To enable it, set the address and certificate in config.yaml:

mcp:
  listen: 0.0.0.0:9443
  tls_cert: /app/sm-mcp/tls/node.pem
  tls_key: /app/sm-mcp/tls/node-key.pem

The certificate must match the name used by clients and be signed by a CA they trust. Restart SM-MCP after changing the configuration.

The client connects to https://mcp.example.org:9443/mcp using a platform account in the Authorization header. Operations are limited to that account's permissions and are read-only. Open the port only to the required clients. Data read by an external client is processed by its model; account for this when choosing a client and granting access.