rigosis-smax-mcp

MCP server for OpenText SMAX, distributed as two deterministic entry points — the command you run determines the toolset permanently, with no runtime probing or switching:

• smax-mcp-agent — 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.
• smax-mcp-user — 11 self-service (ESS) 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. smax-mcp-agent additionally needs the "Access OData API" role; smax-mcp-user 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. It installs the end-user toolset (smax-mcp-user) by default; operators run smax-mcp-setup --agent instead to wire up smax-mcp-agent. If it ends with a success confirmation, you're done — the sections below are the manual alternative.

Migrating from 0.8.x

The old single smax-mcp command and its mode-switching environment variable are gone; rerun smax-mcp-setup to regenerate your client config.

Verify your setup first

uvx --from rigosis-smax-mcp smax-mcp-verify --profile agent   # or --profile user

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). --profile also checks that profile's API surface: user does one harmless ESS read; agent checks EMS Request access — a 403 there prints a warning but still exits 0 (a restricted agent account is still a valid agent login); any other failure exits 1.

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_SETUP_PROFILE, and SMAX_MCP_LANG; the wizard then skips every question (and, when the profile is preset, the profile-confirmation 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, smax-mcp-user auto-detects the response language from the signed-in user's SMAX profile (person/me Locale).

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. Pick the command for your profile — smax-mcp-agent (shown below) or smax-mcp-user. Generic client configuration:

• command: uvx
• args: ["--from", "rigosis-smax-mcp", "smax-mcp-agent"]
• 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-agent

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "smax": {
      "command": "uvx",
      "args": ["--from", "rigosis-smax-mcp", "smax-mcp-agent"],
      "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.