Matrix42

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

| list_operations | search?, service_id?, limit? | Operations as {id, name, method, path, service, documentation}. search filters on name, documentation, and service name. Defaults t