Power your agent
Lệnh của chính nhà phát hành. Không phải endpoint của PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code không có liên kết cài đặt cho lệnh cục bộ. Sao chép lệnh bên dưới và chạy trong terminal.
claude mcp add matrix42-mcp -- npx -y matrix42-mcp@0.1.6Chạy trong terminal.
{ "mcpServers": { "matrix42-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
URL từ xa hay một lệnh trên máy của bạn? Hai cách cài đặt khác nhau thế nào
Chạy trên PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Mở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.
confirm. The preview is the same plan object that gets executed, so it cannot drift.Understand it
Set it up
Use it
Work on it
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.
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.
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
403because of role/audience restrictions.
All configuration is via environment variables.
¹ Provide either M42_API_TOKEN or both M42_USERNAME and M42_PASSWORD.
The server runs over stdio: your MCP client starts it. No install step is needed - npx fetches
it on demand.
claude mcp add matrix42 \
--env M42_HOST=https://matrix42.example.com \
--env M42_API_TOKEN=your-api-token \
-- npx -y matrix42-mcp
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/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"
}
}
}
}
.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.
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
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 actionsTypical flow: api_overview once → list_operations with a search term → describe_operation
on the one you want.
schema_discovery actionsTypical flow: schema_overview → list_* with a search term → describe_* → get_pickup_values
before filtering on any pickup attribute.
data_query actionsTypical 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.
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 actionsEvery 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.
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:
notify_initiator, notify_users and notify_responsible
all default to false; closing a ticket does not mail anyone unless you ask.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.
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:
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.
.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.M42_TOOLS if you only want part of it.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.
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.
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.
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:
src/domains.ts.src/*-guide.ts / src/*-overview.ts (then run npm run docs).Before opening a pull request:
npm run typecheck && npm test && npm run build
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.
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.
Found a vulnerability? Please report it privately rather than in a public issue - see SECURITY.md.
MIT © 2026 S&S Technologies GmbH
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.
Model Context Protocol server for Matrix42 — lets AI assistants explore the API, read the data model, search the service desk, and act on tickets
{ "mcpServers": { "matrix42-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Công cụ
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Bản ghi này không liệt kê biến môi trường bắt buộc nào.
Matrix42 chạy cục bộ qua stdio.
Kiểm tra lần cuối: 2026-11-15. Model Context Protocol server for Matrix42 — lets AI assistants explore the API, read the data model, search the service desk, and act on tickets