Matrix42 MCP Server

Give your AI assistant a safe, read-only-by-default window into Matrix42.

A Model Context Protocol server that lets an assistant explore a

Matrix42 instance the way an experienced consultant would: find the right web service, read the real

data model, query records with valid filters, search the service desk, and - only if you switch it

on - act on tickets.

The server holds the credentials and talks to Matrix42 on the assistant's behalf: it performs the

API-token exchange, sets the `Explicit-Language` header, and handles TLS. **The assistant never sees

your credentials.**

npx matrix42-mcp --help

> [!IMPORTANT]

> This is an independent community project. It is **not affiliated with, endorsed by, sponsored

> by, or supported by Matrix42 AG.** "Matrix42" is a trademark of its respective owner and is used

> here only to describe what this software interoperates with. Support comes from the community via

> GitHub issues - **do not contact Matrix42

> support about this project**, and do not expect a service-level agreement of any kind. It is

> provided "as is" under the MIT licence.

> [!NOTE]

> Status: early release. The server is read-only by default - write tools are not even listed

> unless you set `M42_ALLOW_WRITES=1`.

Highlights

• Read-only by default. Write tools are absent from the tool list unless explicitly enabled.
• Never guesses. Every column is resolved against your instance's live schema before a query

runs, so a field your instance does not have is reported - not sent and turned into an opaque 500.

• Teaches, then acts. Four written guides ship with the server as MCP resources, covering the

data model, the schema, the ASQL filter language and the REST conventions.

• Preview before you write. Every write returns the exact request it *would* send until you

pass `confirm`. The preview is the same plan object that gets executed, so it cannot drift.

• Safe defaults where it counts. Notification e-mails are off, journal entries are internal, and

cascading closes are opt-in.

• No Matrix42 code or content. Every guide is original prose that links to the official docs

rather than reproducing them.

Table of contents

Understand it

• Why
• What it can do
  • What a conversation looks like

Set it up

• Requirements
  • Creating an API token
• Configuration
• Client setup
  • Claude Code
  • Claude Desktop
  • Cursor
  • VS Code (GitHub Copilot)
• Verifying the connection

Use it

• Tools and actions
  • `webservice_discovery` actions
  • `schema_discovery` actions
  • `data_query` actions
    • Links into the web interface
  • `service_desk` actions
  • `ticket_actions` actions (writing data)
    • Preview, then confirm
  • Prompts
  • Resources
• Security notes

Work on it

• Development
  • How it fits together
  • Layout
• Roadmap
• Contributing
• Support
• Project
• Security
• License

Why

Matrix42's API surface is large (a typical instance exposes ~190 web services and ~1,100 operations),

plus a data model of ~800 data definitions and ~240 configuration items, and an assistant has no way

to know what exists. Point it at this server and it can search for the

right endpoint, read the exact contract, and then write correct integration code - instead of

guessing at URLs, auth, and headers.

What it can do

What a conversation looks like

> You: Which open hardware tickets are still unresolved, and are any past their service level?

The assistant works it out without you naming a single id:

Note what did not happen: no GUID lookups, no guessed attribute names, and nothing was written. Note also what the server refuses: a filter Matrix42 accepts but never applies, so an unfiltered answer is never mistaken for a filtered one.

Requirements

• Node.js 22.19 or newer (required by undici, the HTTP client)
• A Matrix42 instance and either an API token (recommended) or basic-auth credentials

Creating an API token

In the Matrix42 Administration application, create an API token for the account the assistant

should act as. The server exchanges it for a short-lived access token automatically and re-exchanges

it before it expires.

> Basic auth is supported but discouraged: many instances accept the credentials yet still refuse API

> access with `403` because of role/audience restrictions.

Configuration

All configuration is via environment variables.

¹ Provide either `M42_API_TOKEN` or both `M42_USERNAME` and `M42_PASSWORD`.

Client setup

The server runs over stdio: your MCP client starts it. No install step is needed - `npx` fetches

it on demand.

Claude Code

claude mcp add matrix42 \
  --env M42_HOST=https://matrix42.example.com \
  --env M42_API_TOKEN=your-api-token \
  -- npx -y matrix42-mcp

Claude Desktop

`claude_desktop_config.json`

(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`)

{
  "mcpServers": {
    "matrix42": {
      "command": "npx",
      "args": ["-y", "matrix42-mcp"],
      "env": {
        "M42_HOST": "https://matrix42.example.com",
        "M42_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project)

{
  "mcpServers": {
    "matrix42": {
      "command": "npx",
      "args": ["-y", "matrix42-mcp"],
      "env": {
        "M42_HOST": "https://matrix42.example.com",
        "M42_API_TOKEN": "your-api-token"
      }
    }
  }
}

VS Code (GitHub Copilot)

`.vscode/mcp.json` - this shape prompts for the token instead of storing it in the file:

{
  "inputs": [
    { "id": "m42-token", "type": "promptString", "description": "Matrix42 API token", "password": true }
  ],
  "servers": {
    "matrix42": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "matrix42-mcp"],
      "env": {
        "M42_HOST": "https://matrix42.example.com",
        "M42_API_TOKEN": "${input:m42-token}"
      }
    }
  }
}

Other stdio-capable clients (Windsurf, Cline, Zed, …) use the same `command` / `args` / `env` shape.

Verifying the connection

Ask the assistant to call `server_info`, or run the bundled smoke test against your instance:

git clone https://github.com/sus-tech-gmbh/M42-MCP.git
cd M42-MCP && npm install && npm run build

M42_HOST=https://matrix42.example.com \
M42_API_TOKEN=your-api-token \
node scripts/smoke.mjs

It connects as a real MCP client and exercises every tool.

You can also run the CLI directly:

npx matrix42-mcp --help    # usage and configuration
npx matrix42-mcp --tools   # available tool ids

Tools and actions

Six tools, each grouping a set of actions. Everything the server can do lives here - the read tools

first, then the one that writes.

`webservice_discovery` actions

Typical flow: `api_overview` once → `list_operations` with a search term → `describe_operation`

on the one you want.

`schema_discovery` actions

Typical flow: `schema_overview` → `list_*` with a search term → `describe_*` → `get_pickup_values`

before filtering on any pickup attribute.

`data_query` actions

Typical flow: `asql_guide` once → `schema_discovery` to find the class and its pickup values →

`validate_asql` → `query`. Always pass `sort` when paging; page boundaries are otherwise unstable.

Numeric enums are decoded for you (`Datatype: 2` → `"Int"`, `Cardinality: 3` → `"Optional (Multi)"`),

and customisations are flagged using the custom prefix the instance itself reports.

Links into the web interface

`data_query(action='deep_link')` builds a URL an assistant can hand you, in the format Matrix42

documents for deep linking:

https://your-instance/wm/app-ServiceDesk/?view-options={"type":"SPSActivityTypeTicket",
                                                        "viewType":"preview",
                                                        "objectId":""}

`view_type` selects what opens: `preview` (default, read-only), `edit`, `new` for a creation form,

or `action` for a wizard. Only `new` works without an object id, and `action` additionally needs an

`action_id`. Nothing is ever changed by opening a link - even `edit` waits for a person to save.

You only need the object id. A base data definition is reused by many configuration items -

`SPSActivityClassBase` alone backs incidents, service requests and changes - so the server resolves

the real one for you rather than making you pick. Pass a wrong `ci_name` and it corrects it; pass a

fragment id and it refuses instead of handing you a link that opens nothing.

Links target the web interface's own origin, not the API host you connected to. Those are often

different: an instance reachable at an IP commonly serves its UUX under a real name, and the shell's

`config.json` says which. Loading the shell from the wrong origin leaves the app calling an origin

it was not served from, which fails after the page has already appeared to load. The server reads

that origin from the instance and reports it as `webInterface` alongside the link; `M42_UI_URL`

overrides it.

`service_desk` actions

Every kind shares the same contract, so one call shape covers the whole service desk. **Only

`subject`, `category_name` and `states` actually filter it** - Matrix42 accepts

`initiator_name`, `ticket_number`, `asset_id` and the rest, then ignores them and returns every

ticket. Passing one is refused rather than handing back an unfiltered result you would read as

filtered; the refusal points at `data_query` with an ASQL `where`, which does filter on those.

`browse` domains: `assets`, `stock_units`, `contracts`, `slas`, `catalog_services`, `bookings`,

`kb_articles`, `approvals`, `imports`, `import_runs`, `workflow_instances`, `workflow_definitions`,

`applications`. Workflows are read-only - this server lists definitions and instances but never

starts, suspends, resumes or cancels them.

Columns are never guessed. Before every `browse`, the server reads the definition's real

attribute list from the instance and keeps only the fields that exist, reporting the rest as

`unavailableFields`. A module you have not licensed therefore yields a shorter row, not a failed

call. The same rule is stated in the guides and the server instructions, so a connected model

follows it too.

All read tools are annotated `readOnlyHint: true`, so clients can distinguish them from anything that

would change data.

`ticket_actions` actions (writing data)

Write tools are absent from the tool list unless `M42_ALLOW_WRITES=1`, so a default deployment

cannot modify anything even if a model asks it to. When enabled, `ticket_actions` offers:

Matrix42 wraps its state machine in these named operations rather than exposing a raw state field,

which is what makes them safe to offer: each carries exactly the parameters its transition needs.

Preview, then confirm

Every action previews by default. Called without `confirm: true`, a write returns the exact

request it would send - method, path, body - along with the consequences worth reading, and changes

nothing:

{
  "wouldChange": true,
  "applied": false,
  "summary": "Close 1 ticket(s)",
  "request": { "method": "POST", "path": "m42Services/api/ticket/Close", "body": { "…": "…" } },
  "effects": ["No notifications are sent and nothing cascades."],
  "next": "Nothing was changed. Show this to the user, and call again with confirm:true to apply it."
}

That preview is the *same plan object* the execute path runs, so it can never describe one request

and send another. Pass `dry_run: true` to force a preview even when `confirm` is set.

Every created ticket also gets an internal journal note recording that it was raised through

this server. Creating through the API otherwise leaves none of the trace the web interface leaves,

so a human picking the ticket up has no way to tell where it came from. The note is never

portal-visible, and if it cannot be written the ticket is still reported as created - losing an

audit line must never look like a failed create. Turn it off with `M42_AUDIT_NOTE=0`, or name the

assistant with `M42_AGENT_LABEL="Acme Helpdesk Assistant"`.

Two further defaults exist to prevent the mistakes that matter most in service management:

• Notification e-mails are off. `notify_initiator`, `notify_users` and `notify_responsible`

all default to `false`; closing a ticket does not mail anyone unless you ask.

• Journal entries are internal. `visible_in_portal` defaults to `false`, so a comment is not

published to the requester's self-service portal by accident.

`close_related_incidents` also defaults to `false`, since it cascades to other tickets.

Prompts

Reusable templates your client can offer (in Claude Desktop, the prompts menu). Each one encodes the

order of operations this server rewards, so a model does not have to rediscover it by failing:

Resources

The written guides are also published as MCP resources, so a client can read them without a tool

call and attach one to a conversation up front:

The same text is checked in under `docs/` so it is readable on GitHub without running

anything - start with **Matrix42 is one graph, not many modules**,

which explains why there is no "Licenses" or "SLAs" table and where those records actually live.

Those files are generated from the guide modules (`npm run docs`), and a test fails if they drift.

Security notes

• The server is a credentialed proxy. Anything the configured account can read through the API,

a connected assistant can reach through the tools it is given. Use an account scoped to what the

assistant actually needs.

• Credentials stay local. They are read from the environment, used only for requests to your

instance, and never written to logs or returned by any tool.

• Never commit `.env`. It is git-ignored; use your client's `env` block or a secret prompt.
• `M42_ALLOW_INSECURE_TLS` disables certificate verification. Use it only for self-signed

development instances, never against production.

• Limit the surface with `M42_TOOLS` if you only want part of it.

Development

npm install
npm run build        # compile to dist/
npm run typecheck    # tsc --noEmit
npm test             # unit tests (vitest)
npm run docs         # regenerate docs/ from the guide modules
node scripts/smoke.mjs                # end-to-end against a real instance
node scripts/service-desk-smoke.mjs   # service desk, domains and lifecycle verbs

`service-desk-smoke.mjs` confines its writes to a single ticket it creates itself, and closes it at

the end; nothing pre-existing is modified and no notification e-mail is ever requested.

How it fits together

Two modules carry the guarantees the rest of the server relies on: `columns.ts` means no projection

is ever sent that the instance cannot answer, and `write-plan.ts` means a preview and its request

are the same object.

Layout

src/
  index.ts           entry point: config → client → MCP stdio server
  config.ts          environment configuration + validation
  m42-client.ts      authenticated HTTP client (token exchange, caching, TLS)
  discovery.ts       fragment queries + projections for services/operations
  schema.ts          schema listings, detail projections, enum decoding, pickup resolution
  api-overview.ts    the static Matrix42 API guide served by api_overview
  schema-overview.ts the static data-model guide served by schema_overview
  data.ts            record queries, paging, result shaping, ASQL validation
  objects.ts         journal, attachments, saved views, current-user identity
  tickets.ts         write operations and their safety defaults
  ticket-verbs.ts    the ticket lifecycle verbs (take over, forward, pause, reopen, …)
  service-desk.ts    the uniform ticket Search contract and the service-level endpoints
  columns.ts         resolves query columns from the live schema instead of assuming them
  domains.ts         the curated domain registry (assets, contracts, catalog, …)
  domain-guide.ts    the "one graph, not many modules" guide
  asql-guide.ts      the static ASQL guide served by asql_guide
  resources.ts       publishes the guides as MCP resources
  prompts.ts         reusable prompt templates
  deep-links.ts      URLs into the Matrix42 web interface (pure string building)
  write-plan.ts      the request a write would send, as a value - the basis of preview/confirm
  tools/             one module per tool, registered from a small registry

Adding a tool means adding a module under `src/tools/` and listing it in `src/tools/index.ts`; its id

then works in `M42_TOOLS` automatically.

Roadmap

• Attachment upload and download
• Approval decisions (approve / reject), which today are read-only
• Per-user tokens, so "my items" can mean an end user rather than the service account

Contributing

Contributions are very welcome - this is a community project and it gets better with more instances

behind it. Matrix42 deployments differ enormously, so **a bug report that quotes the exact request

and the exact error is worth a lot**: it is often the only way to learn that an attribute or an

operation behaves differently elsewhere.

Good first contributions:

• A domain that matters to you but is missing from `src/domains.ts`.
• A correction to a guide in `src/*-guide.ts` / `src/*-overview.ts` (then run `npm run docs`).
• A failing case from your instance, with the request and response, as an issue.

Before opening a pull request:

npm run typecheck && npm test && npm run build

Support

Community support only, through

GitHub issues and

discussions. There is no SLA, and

Matrix42 AG cannot help you with this project - please do not open a ticket with them about it.

Project

Releases are published from CI when a GitHub Release is published, using npm trusted publishing - no long-lived npm token exists anywhere, and every tarball carries provenance linking it to the commit and workflow run that built it.

Security

Found a vulnerability? Please report it privately rather than in a public issue - see

SECURITY.md.

License

MIT © 2026 S&S Technologies GmbH

Disclaimer

This project is an independent, community-maintained integration. It is **not affiliated with,

endorsed by, sponsored by, or supported by Matrix42 AG**. "Matrix42" and any related marks belong to

their respective owners and are used here solely to identify the software this project

interoperates with. No Matrix42 source code or documentation is redistributed in this repository.

The software is provided "as is", without warranty of any kind. You are responsible for the account

you configure it with and for anything an assistant does through it - read

Security notes before pointing it at a production instance.