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; agent-level EMS permissions are the tenant's role configuration.
• smax-mcp-user — 11 self-service (ESS) portal tools, live-verified against real tenants: search the portal (articles, news, offerings), browse the entitled service catalog, conduct an offering's form field-by-field via the portal's own form engine (valid values, dependencies, entity-link lookups, mandatory base fields), create and track requests behind a duplicate/related-news confirmation gate, comment, and approve or deny approval tasks. Everything runs strictly as the signed-in end user under the portal's own entitlements — the ESS toolset gains no agent capability from any role.

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. Every PAT-using account needs the "Access OData API" role — without it SMAX hides the Personal Access Tokens screen, so the user cannot create a PAT. The role only gates PAT management: it does not grant EMS record/offering access and does not make an end user an agent — smax-mcp-user stays entirely inside the portal's own entitlement-scoped ESS endpoints.

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.