Installing the SC4S MCP Server¶

The SC4S MCP server is distributed as a container image. It can accept remote connections over Streamable HTTP or run locally using the stdio transport.

Prerequisites¶

SC4S MCP server is currently available only for Podman or Docker runtimes.

• A running SC4S instance exposing the management REST API (default port 8080).
• Docker or Podman on the host where the MCP server will run.
• An MCP-compatible AI assistant or agent that can connect to the server over stdio or streamable HTTP (for example: Cursor, Claude Desktop, or Visual Studio Code with an MCP extension).

Prepare your SC4S instance¶

Before running the MCP server, make sure your SC4S instance is properly configured.

• Enable SC4S management API - by default SC4S API exposes only the /health endpoint. The configuration and metadata endpoints are disabled. To enable them, set SC4S_API_MANAGEMENT_ENABLED to true in your SC4S env_file (see SC4S management API).
• Configure SC4S API authentication - authentication is required when management endpoints are enabled. Set SC4S_AUTH_TOKEN_FILE to a readable, non-empty token file; the API refuses to start without it. See SC4S management API authentication.
• Mount env_file - some MCP management tools need to read and write SC4S’s env_file at runtime. The --env-file flag alone is not sufficient: it only injects variables at startup and does not make the file writable inside the container. To make env_file accessible to the SC4S process, you need to bind-mount it into the container. If you are using systemd, follow the steps below:

1. Add a new environment variable to the service file (by default located at /lib/systemd/system/sc4s.service):

   Environment="SC4S_ENV_FILE_MOUNT=/opt/sc4s/env_file:/opt/sc4s/env_file:z"
   

2. Add -v $SC4S_ENV_FILE_MOUNT to your ExecStart alongside the other -v flags:

   ExecStart=/usr/bin/podman run \
           -e "SC4S_CONTAINER_HOST=${SC4SHOST}" \
           -v "$SC4S_PERSIST_MOUNT" \
           -v "$SC4S_LOCAL_MOUNT" \
           -v "$SC4S_ARCHIVE_MOUNT" \
           -v "$SC4S_TLS_MOUNT" \
           -v "$SC4S_ENV_FILE_MOUNT" \
           --env-file=/opt/sc4s/env_file \
           --network host \
           --name SC4S \
           --rm $SC4S_IMAGE
   

3. If SC4S runs as the non-root syslog user (UID/GID 1024), make the mounted file readable and writable by that user:

   sudo chown 1024:1024 /opt/sc4s/env_file
   sudo chmod 600 /opt/sc4s/env_file
   

   Use the mapped host UID/GID if your container runtime uses user namespace remapping. An unreadable file is skipped during startup, but management tools cannot read or update it until permissions are corrected.

4. Reload and restart the systemd service:

   sudo systemctl daemon-reload
   sudo systemctl restart sc4s
   

SC4S MCP configuration reference¶

The MCP server is configured through environment variables.

Run the container¶

You can pull the latest SC4S MCP image from the registry: ghcr.io/splunk/splunk-connect-for-syslog/container3mcp.

Connect to SC4S¶

Set SC4S_API_URL to an address the MCP container can reach. If SC4S runs on another host, use its hostname or IP address, for example https://sc4s.example.com:8080.

If SC4S and the MCP server run as separate containers on the same host, choose one of these networking options:

• With host networking, run the MCP container with --network host and set SC4S_API_URL=http://127.0.0.1:8080.
• With a shared container network, attach both containers to the same network and use the SC4S container name, for example SC4S_API_URL=http://SC4S:8080.

Create the shared network once:

docker network create sc4s-network
# or: podman network create sc4s-network

Add --network sc4s-network when starting both SC4S and the MCP server. For the MCP container, use:

--network sc4s-network \
-e SC4S_API_URL=http://SC4S:8080

When SC4S uses a bridge network, publish the syslog listener ports required by your devices. Port 8080 does not need to be published because the MCP container can reach it over the shared network.

Deploy for remote MCP clients¶

For remote access, configure an allowed hostname, bearer-token authentication, and TLS. The example below uses mcp.example.com and expects its certificate and private key in /opt/sc4s-mcp/tls.

Create an MCP token:

mkdir -p /opt/sc4s-mcp/secrets
python -c "import secrets; print(secrets.token_urlsafe(32))" \
  > /opt/sc4s-mcp/secrets/mcp_token
chmod 600 /opt/sc4s-mcp/secrets/mcp_token
sudo chown 10001:10001 /opt/sc4s-mcp/secrets/mcp_token # if you are using docker remapping make sure to use correct uid and gid

Run the container:

docker run -d \
  -p 8000:8000 \
  -e SC4S_MCP_ALLOWED_HOSTS=mcp.example.com \
  -v /opt/sc4s-mcp/secrets/mcp_token:/run/secrets/sc4s_mcp_token:ro \
  -e SC4S_MCP_AUTH_TOKEN_FILE=/run/secrets/sc4s_mcp_token \
  -v /opt/sc4s-mcp/tls:/etc/sc4s-mcp/tls:ro \
  -e SC4S_MCP_TLS_CERT=/etc/sc4s-mcp/tls/server.crt \
  -e SC4S_MCP_TLS_KEY=/etc/sc4s-mcp/tls/server.key \
  -e SC4S_API_URL=http://<SC4S_HOST>:8080 \
  --name sc4s-mcp \
  ghcr.io/splunk/splunk-connect-for-syslog/container3mcp

Replace docker with podman when using Podman. If SC4S uses host networking on the same Linux host, replace -p 8000:8000 with --network host and set SC4S_API_URL=http://127.0.0.1:8080. If both containers use sc4s-network, add --network sc4s-network and set SC4S_API_URL=http://SC4S:8080.

If the SC4S API requires authentication, add SC4S_API_TOKEN_FILE as shown in SC4S API authentication.

Local HTTP testing¶

For testing with an MCP client on the container host, the endpoint can be published on loopback without configuring TLS:

docker run -d \
  -p 127.0.0.1:8000:8000 \
  -e SC4S_API_URL=http://<SC4S_HOST>:8080 \
  --name sc4s-mcp \
  ghcr.io/splunk/splunk-connect-for-syslog/container3mcp

Replace docker with podman when using Podman. The local client connects to http://127.0.0.1:8000/mcp.

Host and origin validation¶

The HTTP transport checks the Host header and, when present, the Origin header before requests reach /mcp. GET /health is exempt from these checks so health probes can reach it.

SC4S_MCP_ALLOWED_HOSTS provides a defense against DNS rebinding attacks. In such an attack, a malicious website changes the DNS records for its hostname to point at your MCP server’s IP address. SC4S_MCP_ALLOWED_HOSTS lists the allowed MCP server’s hostnames or IP addresses.

For example, if the MCP server runs in a container on EC2 with public IP 203.0.113.10, configure the server address used by your local MCP client:

By default, only localhost, 127.0.0.1, and [::1] are accepted.

To accept any hostname or IP address on any port, set:

-e SC4S_MCP_ALLOWED_HOSTS='*'

Native MCP clients normally omit the Origin header and need no SC4S_MCP_ALLOWED_ORIGINS setting. If a browser-based client connects directly to the MCP server, also allow the exact origin of the website running that client:

-e SC4S_MCP_ALLOWED_ORIGINS=https://browser.example.com

Origins include the scheme and, when non-default or explicitly sent, the port. For example, https://browser.example.com and https://browser.example.com:8443 are different allowed origins.

To allow any Origin set:

-e SC4S_MCP_ALLOWED_ORIGINS='*'

The image ships a healthcheck that verifies the /health endpoint. Check the container status with:

docker ps   # or: podman ps

SC4S API authentication¶

The SC4S management REST API requires authentication for management endpoints. The MCP server must present the same bearer token. Configure authentication on SC4S as described in SC4S management API authentication.

Mount the file containing that same token in the MCP container and add these options to the docker run or podman run command:

-v /opt/sc4s-mcp/secrets/sc4s_api_token:/run/secrets/sc4s_api_token:ro \
-e SC4S_API_TOKEN_FILE=/run/secrets/sc4s_api_token

The token file should be readable only by the account running the container:

chmod 600 /opt/sc4s-mcp/secrets/sc4s_api_token
sudo chown 10001:10001 /opt/sc4s-mcp/secrets/sc4s_api_token # if you are using docker remapping make sure to use correct uid and gid 

You can use SC4S_API_TOKEN instead, but an environment variable can be visible in container inspection output. When both token settings are empty, no Authorization header is sent to the SC4S API.

If the SC4S API is served with a self-signed or private CA certificate, set SC4S_API_CA_CERT to the path of the CA certificate inside the container so the MCP server can verify it.

MCP server authentication¶

Token authentication between MCP clients and the SC4S MCP server is configured with SC4S_MCP_AUTH_TOKEN or SC4S_MCP_AUTH_TOKEN_FILE. When either setting is present, every request to /mcp must carry an Authorization: Bearer <token> header that matches the configured value; mismatches return HTTP 401.

Use a unique, randomly generated token of at least 32 bytes. A token file keeps the value out of process listings and container inspection output. When both token settings are empty, authentication is disabled.

Configure the MCP client to send the token in the Authorization header on every request to /mcp (see Generic MCP client configuration below).

TLS¶

Remote connections should use TLS. Set SC4S_MCP_TLS_CERT and SC4S_MCP_TLS_KEY to serve /mcp and /health over HTTPS. If only one is set, the server refuses to start.

When clients connect using a non-loopback server hostname or IP address, add that server address to SC4S_MCP_ALLOWED_HOSTS as described in Host and origin validation.

When both settings are empty, the server uses HTTP. TLS can also be terminated by a reverse proxy. In that configuration, publish the container on host loopback with -p 127.0.0.1:8000:8000 and have the proxy forward requests to that address.

If the private key is encrypted, also pass -e SC4S_MCP_TLS_KEY_PASSWORD="$PASS".

When using a self-signed certificate, install the issuing CA in the operating system or MCP client trust store.

Make sure that the certificate and key have file permissions that will allow MCP process to access it. You can do this by running:

sudo chown 10001:10001 <your-cert-and-key> # if you are using docker remapping make sure to use correct uid and gid 

Generic MCP client configuration¶

Most MCP clients accept one of two connection styles. Consult your client’s documentation for the exact configuration file and its location; the shape of the configuration is typically the same across clients.

Remote endpoint (Streamable HTTP): the client connects to the single /mcp HTTP endpoint exposed by the server. Provide:

• a url pointing at https://<MCP_HOST>:8000/mcp,
• a headers map carrying Authorization: Bearer <TOKEN>, plus any other headers required by your deployment.

For example, the corresponding .cursor/mcp.json for Cursor on a remote workstation is:

{
  "mcpServers": {
    "sc4s": {
      "url": "https://<MCP_HOST>:8000/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Local process (stdio): the client launches the server as a child process and communicates via standard input/output. Provide:

• a command to execute (for example docker or podman),
• an args array that starts the MCP server,
• optional environment variables (SC4S_API_URL, MCP_TRANSPORT=stdio).

Codex MCP client configuration¶

codex mcp add sc4s --url http://<MCP_HOST>:8000/mcp

Replace with the hostname or IP address that the MCP client can use to reach the MCP server.

Claude Code MCP client configuration¶

Store the MCP bearer token in an environment variable, then register the server with the claude CLI:

export SC4S_MCP_TOKEN="<TOKEN>"
claude mcp add --transport http sc4s https://<MCP_HOST>:8000/mcp \
  --header 'Authorization: Bearer ${SC4S_MCP_TOKEN}'

Replace <MCP_HOST> with the hostname or IP address that the MCP client can use to reach the MCP server, and <TOKEN> with the value configured in SC4S_MCP_AUTH_TOKEN or SC4S_MCP_AUTH_TOKEN_FILE.

Keep the single quotes around the header. Claude Code then stores the ${SC4S_MCP_TOKEN} placeholder and expands it each time it connects, so SC4S_MCP_TOKEN must be set in the environment that starts Claude Code. If you pass the token itself, Claude Code saves it in plain text in ~/.claude.json.

By default, the server is added for the current project only. Add --scope user to make it available in every project.

If the MCP server certificate is issued by a private or self-signed CA, set NODE_EXTRA_CA_CERTS to the CA certificate before starting Claude Code:

export NODE_EXTRA_CA_CERTS=/path/to/ca.pem
claude

Run /mcp in Claude Code to confirm that the sc4s server is connected. To install the SC4S skills for Claude Code, see SC4S Plugin.

Verify the installation¶

1. Confirm the container is running: docker ps or podman ps.
2. Confirm the MCP client sees the server. Most clients list available MCP servers in a dedicated panel or on startup.
3. From the assistant, call the sc4s_health tool. A healthy instance returns a status payload from the SC4S management API. An error like "SC4S instance unreachable at http://..." means the MCP server could reach out but SC4S is not answering. Check SC4S_API_URL, the SC4S container status, and network connectivity.

Upgrading¶

The MCP server version must match the SC4S version it manages. Before upgrading, record the image tag or digest used by the running MCP container and keep its current configuration. Pull the replacement image before stopping the existing container. No data migration is required.

Docker:

docker stop sc4s-mcp && docker rm sc4s-mcp
docker pull ghcr.io/splunk/splunk-connect-for-syslog/container3mcp

Podman:

podman stop sc4s-mcp && podman rm sc4s-mcp
podman pull ghcr.io/splunk/splunk-connect-for-syslog/container3mcp

Then run the same docker run or podman run command used for the previous version.