Matrix42

Matrix42 MCP Server

[CI] [npm version] [node] [License: MIT] [MCP] [PRs welcome]

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.

[You ask an AI assistant; the assistant talks to matrix42-mcp over MCP; matrix42-mcp talks to your Matrix42 instance over REST. Credentials stay in the server and never reach the assistant.]

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:

[The assistant searches tickets by category and state, checks the service level of each, builds a deep link for the one at risk, and answers - without looking up a single id or writing anything.]

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.gitcd 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 configurationnpx 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":"<object id>"}

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 installnpm run build        # compile to dist/npm run typecheck    # tsc --noEmitnpm test             # unit tests (vitest)npm run docs         # regenerate docs/ from the guide modulesnode scripts/smoke.mjs                # end-to-end against a real instancenode 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

[Layered architecture: the MCP surface sits on domain modules, which sit on the correctness and safety layer, which sits on the authenticated client.]

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.