rigosis-smax-mcp

MCP server for OpenText SMAX. The server has two modes, auto-detected at startup via a capability probe (forceable with SMAX_MCP_MODE): agent mode — work with EMS records (Incidents, Requests, Changes, People, Devices, custom types), comments, and attachments from any MCP client; fifteen generic tools including live schema discovery (describe_entity, list_entity_types) and warn-first write validation; requires the "Access OData API" role — and end-user (ESS) mode — 11 self-service portal tools, live-verified against a real tenant; no OData role needed.

rigosis-smax-mcp is developed and licensed by Rigosis for integration with OpenText™ Service Management software, formerly known as SMAX. It is not an OpenText product.

Requirements

• uv (provides uvx; installs its own Python)
• A SMAX user and a Personal Access Token (Service Portal → Personal Access Tokens), or username/password. Agent mode additionally needs the "Access OData API" role; end-user (ESS) mode does not.

Quick setup (recommended)

uvx --refresh --from rigosis-smax-mcp smax-mcp-setup

An interactive wizard: asks for your connection details, tests them live against your tenant, writes the Claude Desktop config for you (backing up any existing file), and prints ready-to-paste snippets for every other MCP client. If it ends with a green checkmark, you're done — the sections below are the manual alternative.

Verify your setup first

uvx --from rigosis-smax-mcp smax-mcp-verify

This checks configuration and authenticates against your tenant before you wire up any client. It reads the environment variables below (a .env file found from the working directory upward also works).

Configuration

Preconfigured install. An admin can bake the whole org setup into one command by pre-setting SMAX_MCP_BASE_URL, SMAX_MCP_TENANT_ID, SMAX_MCP_SYSTEM_NAME, SMAX_MCP_MODE, and SMAX_MCP_LANG; the wizard then skips every question (and, when the mode is preset, the probe and the mode-override prompt) and each end user only types their username and token. SMAX_MCP_LANG sets both the wizard's display language and the assistant's runtime response language, so one variable covers a single-language org. Without SMAX_MCP_LANG, the server auto-detects the response language from the signed-in user's SMAX profile (person/me Locale) in ESS mode.

Use a least-privilege SMAX integration account — every tool acts as that one configured user.

Connect an MCP client

The server speaks MCP over stdio. Generic client configuration:

• command: uvx
• args: ["--from", "rigosis-smax-mcp", "smax-mcp"]
• environment: the variables above

Claude Code:

claude mcp add smax \
  --env SMAX_MCP_BASE_URL=https://smax.example.com \
  --env SMAX_MCP_TENANT_ID=123456789 \
  --env SMAX_MCP_USERNAME=integration.user \
  --env SMAX_MCP_PAT=your-token \
  --env SMAX_MCP_ATTACHMENTS_DIR=/path/to/attachments \
  -- uvx --from rigosis-smax-mcp smax-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "smax": {
      "command": "uvx",
      "args": ["--from", "rigosis-smax-mcp", "smax-mcp"],
      "env": {
        "SMAX_MCP_BASE_URL": "https://smax.example.com",
        "SMAX_MCP_TENANT_ID": "123456789",
        "SMAX_MCP_USERNAME": "integration.user",
        "SMAX_MCP_PAT": "your-token",
        "SMAX_MCP_ATTACHMENTS_DIR": "C:\\smax-attachments"
      }
    }
  }
}

Windows note: SMAX_MCP_ATTACHMENTS_DIR takes a normal Windows path; create the directory before first use.

In a session, call whoami first as a connectivity smoke test.

Support

Contact your Rigosis representative. Use of this software is governed by the LICENSE file and your agreement with Rigosis Information Systems.