Deploy AI Integration

Verify the checksum before installing

If a hash doesn't match: don't run the binary then re-download both files from the original source and check again.

mcp-server

orchestrator

Generating token values for MCP_INBOUND_TOKEN / ORCH_INBOUND_TOKEN

MCP_INBOUND_TOKEN and ORCH_INBOUND_TOKEN are not issued by Archibus; they are opaque static bearer secrets the customer generates and assigns themselves, purely to authenticate calls between these two services and from Web Central. Any sufficiently long random string works; there is no token-issuing endpoint or format requirement to satisfy.

Generate each one as a long random string (32 bytes / 256 bits of randomness is a reasonable minimum) using whatever tool is available on your platform:

Paste the generated value straight into the relevant env file(s) with no surrounding whitespace or quotes. Treat these like any other credential: don't commit them to source control, and restrict read access on whichever env file, systemd EnvironmentFile=, launchd wrapper script, or WinSW service XML holds them to the service account and administrators only.

Install as an unattended background service

Both binaries are plain console executables with no built-in service/daemon code. Each platform's native service manager supervises the process (auto-start on boot, restart on crash). Service unit/plist/XML templates ship inside every release archive under service-templates/.

Linux — system

Templates: service-templates/linux/archibus-mcp-server.service, archibus-orchestrator.service.

1. Extract the archive, for example. /opt/archibus-mcp-server/
2. Create the service account referenced by the unit's User= (or edit it to an existing one), for example useradd --system --no-create-home archibus-mcp
3. Write the env file the unit expects, for example, /etc/archibus-mcp-server/mcp-server.env (plain KEY=value lines, same variable names as .env.example). Repeat for the orchestrator's env file.
4. Ensure the service account can write the log directory, either create /var/log/mcp-server and chown it to the service account, or set LOG_FILE in the env file to a path it already owns.
5. Copy the unit files to /etc/systemd/system/, then reload the daemon and enable both units:

sudo systemctl daemon-reload
sudo systemctl enable --now archibus-mcp-server
sudo systemctl enable --now archibus-orchestrator

6. systemctl gives boot-start and restart-on-failure (Restart=on-failure in the unit) for free. systemctl status archibus-mcp-server and journalctl -u archibus-mcp-server remain available even though the app also keeps its own file log.

Update: stop the service, replace the binary, start the service.

Uninstall: disable the service, remove the unit file, reload the daemon.

macOS — launchd

Templates:

• service-templates/macos/ 
• 2 plists (com.eptura.archibus-mcp-server.plist, com.eptura.archibus-orchestrator.plist)
• 2 wrapper-script templates

The launchd plists have no equivalent of systemd's EnvironmentFile=, so each plist's ProgramArguments points at a small wrapper script that sources the env file and execs the real binary.

1. Extract the archive, for example, /opt/archibus-mcp-server/
2. Copy launch-mcp-server.sh.template to /opt/archibus-mcp-server/launch-mcp-server.sh (and the orchestrator counterpart), and mark both executable.
3. Write the env files the wrapper scripts source (mcp-server.env, orchestrator.env).
4. Choose daemon vs. agent: /Library/LaunchDaemons/ (system-wide, runs at boot with no user logged in, requires elevated access) is the right choice for an unattended server; ~/Library/LaunchAgents/ (per-user, no elevated access needed) only runs while that user is logged in.
5. Copy the plist(s) into the chosen directory, then load both:

sudo launchctl load /Library/LaunchDaemons/com.eptura.archibus-mcp-server.plist
sudo launchctl load /Library/LaunchDaemons/com.eptura.archibus-orchestrator.plist

Note, drop the elevated-access prefix and use the LaunchAgents path for the per-user variant.

Update: unload, replace the binary, load again.

Uninstall: unload, then remove the plist.

Windows — WinSW

Templates:

• service-templates/windows/mcp-server-service.xml, orchestrator-service.xml

Windows has no built-in systemd/launchd equivalent, so this uses WinSW which is a small, well-established wrapper for running an existing executable as a Windows Service. No in-binary Windows service code is required.

1. Extract the archive to C:\archibus-mcp-server\
2. Download WinSW's latest executable and rename it to archibus-mcp-server.exe (WinSW pairs a name.exe with a matching name.xml), placed next to mcp-server.exe. Repeat with archibus-orchestrator.exe next to orchestrator.exe.
3. Copy mcp-server-service.xml to archibus-mcp-server.xml alongside the renamed WinSW exe (and the orchestrator counterpart), and fill in the env values in the XML.
4. From an elevated prompt, install and start both services:

archibus-mcp-server.exe install
archibus-mcp-server.exe start
archibus-orchestrator.exe install
archibus-orchestrator.exe start

5. Both services are now visible in services.msc, with onfailure-triggered restart configured in the XML. The XML deliberately disables WinSW's own log capture and the app writes its own rotating file log (see Logging configuration below); don't double-log.

Update: stop the service, replace the binary, start the service.

Uninstall: stop the service, then uninstall it.

Set the ai.properties values

Both properties live in a single file in the WebCentral project: WEB-INF/config/ai.properties. It ships with both keys present but empty:

# Base URL of the AI orchestrator service.
# Example: archibus.ai.baseUrl=http://localhost:8090
archibus.ai.baseUrl=
# Bearer token presented to the orchestrator on each request.
# Example: archibus.ai.apiKey=your-base64-token-here

Where:

Service won't start

401 / authentication errors between the two services

mcp-server can't reach WebCentral

orchestrator / LLM provider errors

WebCentral integration issues

General diagnostic steps

1. Confirm both binaries are running the version you deployed and check the version line each logs on startup.
2. Check each service's /health endpoint directly (see Verify the deployment above) to isolate whether a failure is in the service itself or in something calling it.
3. Tail the rotating log file (see Logging configuration above) rather than relying on the service manager's own log capture. The app's own JSON log line provides more details than a generic "service failed" message from systemd/launchd/WinSW.
4. Change one variable at a time and restart. The token mismatches, wrong URLs, and missing Azure-only variables account for the large majority of configuration issues seen in practice.