Skip to content

Releases

v0.5.0

Choose a tag to compare

@ponmeloco ponmeloco released this 17 Sep 15:44

A minor release that rebuilds the tool surface around the questions an operator asks, rather than around the objects the API exposes. Twenty-three tools are gone and twenty-six are new. The server decides what is a cause and what is a consequence, what is noise, and where a measured value is heading, so a model reports and explains instead of computing. It also ships oitc-mcp-eval, which measures whether the model you plan to run can actually do that on your data.

Warning

This release breaks clients. Twenty-three tool names are gone, each with a named replacement below. Read ## Tools before you move a pinned instance. This is still 0.x, where a minor bump may break a client.

Warning

Delegated mode is still a preview. It depends on user tokens issued by openITCOCKPIT, which ship with an upcoming openITCOCKPIT release. Everything else in 0.5.0 works with openITCOCKPIT 5.6 and newer today.

Image openitcockpit/mcp-server:0.5.0 · amd64 + arm64
Digest sha256:d6ce07f38ea0bf43f657fa329e1327bfe211c32c956dbf211578adad95b84c81
Requires openITCOCKPIT 5.6 or newer · delegated mode (preview): an upcoming openITCOCKPIT release with user tokens
License MIT

What is broken, and what is only a consequence

get_problem_overview()

A model handed 312 critical services reports 312 problems. An operator has one: the switch they all sit behind. The overview reports a down host once, with the unreachable hosts and the services behind it folded underneath, keeps what nobody has picked up apart from what is acknowledged or in a downtime, and says when the monitoring engine itself is behind - stale results look exactly like an outage.

investigate_problem answers why: when it began, whether it happened before and for how long, what else failed in the same minutes, and which configuration changes and exports came first. find_noisy_checks names what generates alerts nobody acts on, each with the setting that would quieten it. explain_notification says why nothing was heard, checking the conditions Naemon checks in the same order. get_shift_summary is a handover.

The rules live in a module with no I/O and are tested against constructed cases, so the decision is inspectable rather than left to whichever model is connected.

Acting on it

acknowledge_problem, remove_acknowledgement, reschedule_check, schedule_downtime and cancel_downtime cover taking a problem on. They wait for the object's own page rather than the list, which lags, so a model cannot report a change that has not happened yet. get_impact says what a host or service carries before it is touched. get_configuration_status and apply_configuration say whether the engine runs the configuration as it stands, and export it.

stop_monitoring, resume_monitoring and delete_object cover the end of an object's life, one tool per intent rather than one per object type.

Reports over a period

get_availability_report(hostname="shop01", days=30)
forecast_metric(hostname="db01", servicename="Disk /")

openITCOCKPIT computes availability only from report definitions saved beforehand, so there was no way to ask for an arbitrary object and window. It is computed here from the state changes recorded for any object. Agreed maintenance is reported apart from the rest rather than deducted silently, because "how available was it" means the figure with it to one person and without it to another. Where the history does not reach back far enough, the report covers what it does cover and says so.

forecast_metric fits a least squares line through the performance data and says when a value reaches its warning or critical threshold. It reports how much of the movement the line explains and gives no date at all when that is too little to stand on: measured on one disk, no forecast over 24 hours and a date 94 days out over a week.

Measuring a model

oitc-mcp-eval --model your-model --samples 3
oitc-mcp-eval --compare
./scripts/eval-throwaway.sh --model your-model

The eval ships with the server. Its cases hold an answer against the numbers the tools returned in that same conversation, so they work on any installation and do not rot as the data ages. Every run is kept in SQLite: the pass rate per case, and what the answer cost in turns, tool calls and tokens. Passing is half the measurement - two models answered everything, one with nine fewer tool calls and a third fewer output tokens. --by-tool and --by-toolset break a run down instead of summing it.

Without --write nothing can change: the tools that change something are never registered. With it, the confirmation names every tool the run could reach, and a tool whose effect cannot be undone is refused unless it is asked for by name.

Nine toolsets, and house style in one file

An instance limited to a toolset is one agent: health investigates and explains but cannot touch anything, onboarding takes hosts into monitoring and nothing else. The sets are health, operations, lifecycle, patch, reporting, catalog, onboarding, config and provisioning. triage is gone; health is what the task became.

OITC_PROMPT_STYLE_FILE names a Markdown file of your own that is added to both general system prompts. One file changes how every agent writes - form of address, house words, which language - without editing prompts that an update overwrites.

Fixed

  • create_hosttemplate and create_servicetemplate enable notifications. The payload left notifications_enabled out, openITCOCKPIT stored 0, and nothing created from such a template ever notified.
  • History windows are computed in the time zone of the user the server acts as. openITCOCKPIT reads them there; computed in the server's own zone, a server in UTC and a user in Europe/Berlin got nothing for the last 24 hours.
  • A list filter is sent as one parameter per element. A host group filter sent as a single value matched nothing.
  • Sorting is by severity, not by state code. desc put unreachable (2) before down (1): of 150 affected hosts the first 20 were all unreachable and the down ones were not listed at all.
  • Times are ISO 8601 with their offset. Asked about a result that carried the zone in a separate field, a model asked which times it applied to.
  • get_allowed_elements_for_container no longer needs OITC_ENABLE_WRITE_TOOLS. It only reads.

Tools

42 tools: 20 read-only, 22 that change something. 16 are unchanged from 0.4.0, 26 are new, and 23 are gone.

gone use instead
get_host_info get_host_health, or find_hosts to search
list_services_by_state find_services, which counts every match per state
list_log_entries investigate_problem, get_shift_summary
get_monitoring_engine_stats get_problem_overview, which says when the engine is behind
list_host_checks, list_service_checks, list_host_state_changes, list_service_state_changes get_host_health, get_service_health, investigate_problem
list_host_downtimes, list_service_downtimes find_downtimes
list_host_acknowledgements, list_service_acknowledgements get_host_health, get_service_health, get_shift_summary
list_hosttemplates, list_servicetemplates, list_commands, list_contacts, list_contactgroups, list_hostgroups, list_servicegroups, list_servicetemplategroups list_catalog(kind=...), which covers all of those plus time periods
list_pending_updates, list_pending_security_updates find_pending_updates, with security_only
create_host_with_agent_pull_mode create_host with agent_pull_port

Run it

docker run -d -p 8000:8000 \
  -e MCP_AUTH_TOKEN="a-token-you-generate" \
  -e OITC_APIKEY="the-openITCOCKPIT-api-key" \
  -e OITC_BASEURL="https://openitcockpit.example.org" \
  openitcockpit/mcp-server:0.5.0

Note

MCP_AUTH_TOKEN is what clients present to this server, OITC_APIKEY is what this server presents to openITCOCKPIT. The server refuses to start if they are equal. Every client that passes the bearer check acts as the one openITCOCKPIT user that key belongs to, so create it for a dedicated, least-privilege user.

Note

Write tools are not registered unless OITC_ENABLE_WRITE_TOOLS=true, whatever a toolset names.

What went into it

Every tool lives in its own file behind one layer that knows openITCOCKPIT's URLs, and a layer of pure logic that knows neither. A tool's name, description, annotations and schema are pinned as a snapshot, so a change to what a model is told fails the tests rather than shipping unnoticed, and a test counts the context each tool and each toolset costs. Another test refuses any text a model reads that names a tool its instance does not have.

Everything here was measured against an instance carrying 500 hosts and 5000 services, built by a script in the repository, and against two models through the eval.

v0.4.0

Choose a tag to compare

@ponmeloco ponmeloco released this 16 Sep 12:01
fca0f3f

A minor release that adds a second way to authenticate. In delegated mode the server holds no openITCOCKPIT credential of its own: it acts as the user each request is for, so one instance can serve many users of the same openITCOCKPIT and each of them sees only their own containers.

Warning

Delegated mode is a preview. It depends on user tokens issued by openITCOCKPIT, which ship with an upcoming openITCOCKPIT release. Until then no released openITCOCKPIT accepts them. Everything else in 0.4.0 works with openITCOCKPIT 5.6 and newer today.

Image openitcockpit/mcp-server:0.4.0 · amd64 + arm64
Digest sha256:001452f6aed400e4fbabdc59adea2428d128d85bd80065531189e503504cf3aa
Requires openITCOCKPIT 5.6 or newer · delegated mode (preview): an upcoming openITCOCKPIT release with user tokens
License MIT

Delegated mode (preview)

OITC_AUTH_MODE=static      # the default - every client acts as the user of OITC_APIKEY
OITC_AUTH_MODE=delegated   # no API key - every request acts as the user it carries a token for

In delegated mode a request carries a short-lived token openITCOCKPIT issued for one user, in X-OITC-User-Token. The server passes it on as Authorization: Bearer with every call it makes, and openITCOCKPIT verifies it and answers with that user's containers and permissions. A request without a token is refused before anything reaches openITCOCKPIT. static stays the default and behaves as before.

  • The token is attached to each outgoing request, never to the shared HTTP session. Concurrent requests for different users use that session at the same time, and a test runs sixteen of them at once without one picking up another's token.
  • Cached scope lookups are kept apart per token, not per the user id inside it, which this server does not verify.
  • OITC_APIKEY must be unset and the http transport is required - there is no user to act for over stdio.

Verified against an openITCOCKPIT that issues these tokens: a user with rights on one tenant sees that tenant's host and not the other's, creates a host in their own tenant but finds no container in the other, and the changelog attributes the change to that user. A forged token is rejected by openITCOCKPIT.

Toolsets as data

oitc-mcp --list-toolsets --format json

prints every set with its description, tools, system prompts, skills and whether it contains a tool that changes anything - read from the tools' annotations, so it cannot disagree with what they do. It follows OITC_TOOLSETS_FILE and needs no credentials, so an installer can create one instance per set before any key exists, without naming a set in its own code.

Fixed

  • get_container_tree without a name starts at the top-most containers the account can see. A user limited to tenants cannot see root and got No container found matching 'root'.
  • HTTP 403 is reported as a missing permission, HTTP 401 as an invalid or expired credential. Both used to point at OITC_APIKEY, which in delegated mode does not exist - and a missing role permission is not fixed by checking a key.

Tools

Unchanged: 39 tools - 24 read-only, 15 write. No tool was added, removed, renamed or given a different parameter.

Run it

docker run -d -p 8000:8000 \
  -e MCP_AUTH_TOKEN="a-token-you-generate" \
  -e OITC_AUTH_MODE="delegated" \
  -e OITC_BASEURL="https://openitcockpit.example.org" \
  -e OITC_TOOLSETS="triage" \
  openitcockpit/mcp-server:0.4.0

Important

Delegated mode is a preview and needs an openITCOCKPIT that issues user tokens - one that accepts Authorization: Bearer <token> and has a signing key from oitc api_tokens --generate-key. These ship with an upcoming openITCOCKPIT release; against any current release every call in delegated mode is rejected. Static mode is unaffected.

Note

Pin 0.4.0, don't follow latest. Still 0.x: the tool set and its parameters have not yet held still across releases.

What went into it

  • #10 - delegated mode, toolsets as JSON, and the container tree for users without root

v0.3.0

Choose a tag to compare

@ponmeloco ponmeloco released this 11 Sep 17:24
370644e

A minor release that changes no tools. It adds a way to give one instance less than all of them: OITC_TOOLSETS limits a server to named subsets of its tool surface, so an agent sees only what its job needs.

Image openitcockpit/mcp-server:0.3.0 · amd64 + arm64
Digest sha256:deabba59b700bc8d2170016bf6bc5d80e590683185d024d3459b03bc56ae276d
Requires openITCOCKPIT 5.6 or newer - one image serves every supported release
License MIT

Toolsets

OITC_TOOLSETS=triage                      # 12 tools instead of 24
OITC_TOOLSETS=triage,get_container_tree   # a set plus one more tool
OITC_TOOLSETS=all                         # everything - the default

A tool that is never registered cannot be called, which makes this a boundary rather than a hint. Six sets ship: triage, patch, catalog, onboarding, config, provisioning. A name that is not a set is taken to be a single tool, so a deployment extends a set without editing anything.

The sets live in toolsets.toml, not in code - read from OITC_TOOLSETS_FILE, else ./toolsets.toml, else the packaged copy. A file found earlier replaces the sets rather than merging with them, and each set's description is what its clients are told the instance is for.

Each shipped set also carries a system prompt supplement, English and German, saying what that role does differently. An instance limited to a set serves its supplement as a resource; an unfiltered one serves none.

Reading back what an instance is limited to

The active sets and their descriptions are served as the resource oitc://skills/oitc-toolsets, as well as in the server instructions. The protocol revision from 2026-07-28 removed the initialize handshake, and with it serverInfo and instructions, so on that path this resource is the only way a client can ask what an instance is for. It also names the tools of each set, which tools/list does not - that list is flat.

One instance per role

docker-compose.roles.yml runs four at once - triage, catalog, patch, and a config instance that may write - each with its own toolset, port, bearer token and openITCOCKPIT API key.

docker compose -f docker-compose.roles.yml up -d

Tools

Unchanged: 39 tools - 24 read-only, 15 write. No tool was added, removed, renamed or given a different parameter.

Run it

docker run -d -p 8000:8000 \
  -e MCP_AUTH_TOKEN="a-token-you-generate" \
  -e OITC_APIKEY="the-openITCOCKPIT-api-key" \
  -e OITC_BASEURL="https://openitcockpit.example.org" \
  -e OITC_TOOLSETS="triage" \
  openitcockpit/mcp-server:0.3.0

Note

Give each instance its own openITCOCKPIT API key. That account's permissions are what every client of the instance acts with, so splitting the tools only means something if the keys differ too.

Note

Pin 0.3.0, don't follow latest. Still 0.x: the tool set and its parameters have not yet held still across releases.

What went into it

  • #8 - toolsets, the system prompt supplements, and the resource that reads them back

v0.2.0

Choose a tag to compare

@ponmeloco ponmeloco released this 07 Sep 14:52
5502e9c

A minor release that changes no tools. What it adds is a second way to get the material that teaches a model how to chain them - over MCP itself - and the entry that lets this server be published to the MCP Registry.

Image openitcockpit/mcp-server:0.2.0 · amd64 + arm64
Digest sha256:2c268fe90d60fa7b68bf515211963a25c96d85cf586bf781b61ae151066832e8
Requires openITCOCKPIT 5.6 or newer - one image serves every supported release
License MIT

Resources and prompts

The skills material is now served over MCP. Until now it was Markdown in the repo that only a Claude Code or Claude Desktop user could copy into a skills directory; a client without that concept had no way to reach it.

Primitive What it carries
Resources at oitc://skills/<name> Every file, as text/markdown. The description a client shows is the skill's own frontmatter description.
Prompts, named after the workflow The oitc-* workflows only - incident triage, patch review, capabilities, and with write tools enabled, host onboarding and configuration change.

Two deliberate asymmetries:

  • The system-prompt files are resources but not prompts. A prompt is inserted as a message; a system prompt belongs in the client's system field, which is exactly what that file says.
  • oitc-host-onboarding and oitc-config-change are registered only when OITC_ENABLE_WRITE_TOOLS=true, the same gate the write tools use. Offering a workflow whose tools are not registered would describe a sequence the server cannot run.

MCP Registry

This is the first version that can be published to the registry, as io.github.openITCOCKPIT/mcp-server.

  • server.json in the repo root carries the entry, validated against the 2025-12-11 schema.
  • The image carries an io.modelcontextprotocol.server.name label, which the registry reads off the published image as its only ownership proof for an OCI package. 0.1.0 carried no labels at all.
  • The declared transport is stdio: a client that runs this container itself has neither a published port nor an MCP_AUTH_TOKEN, so the declared environment defaults say stdio too.

Tools

Unchanged: 39 tools - 24 read-only, 15 write, the write half still not registered unless you switch it on. No tool was added, removed, renamed or given a different parameter.

Run it

docker run -d -p 8000:8000 \
  -e MCP_AUTH_TOKEN="a-token-you-generate" \
  -e OITC_APIKEY="the-openITCOCKPIT-api-key" \
  -e OITC_BASEURL="https://openitcockpit.example.org" \
  openitcockpit/mcp-server:0.2.0

Note

The skills folder moved to src/openitcockpit_mcp/skills/. It has to live inside the package to be served over MCP, and one copy is better than two. The folder layout is unchanged, so cp -r src/openitcockpit_mcp/skills/oitc-* ~/.claude/skills/ replaces the old path. This affects clones only - the 0.1.0 image never contained the folder.

Note

Pin 0.2.0, don't follow latest. Still 0.x: the tool set and its parameters have not yet held still across releases, so a minor bump may break a client - even one like this, which does not touch them.

What went into it

  • #3 - serve the skills material as MCP resources and prompts
  • #4 - add the MCP Registry entry and its ownership label

Full tool reference and configuration: README · CHANGELOG

v0.1.0

Choose a tag to compare

@ponmeloco ponmeloco released this 03 Sep 11:57

The first release of an MCP server that gives an LLM client read access to an openITCOCKPIT monitoring instance - and, if you switch it on, the ability to change its configuration.

Image openitcockpit/mcp-server:0.1.0 · amd64 + arm64
Digest sha256:b954c21581f378293d30e7d3ec02e9efea1bc9948e174391d1d6b23237085f80
Requires openITCOCKPIT 5.6 or newer - one image serves every supported release
License MIT

What it can do

39 tools - 24 read-only, 15 write.

Status Host and service status, alert log entries, monitoring engine health
Incidents Downtimes, acknowledgements, check history, state changes
Configuration Host and service templates, commands, contacts, groups, the container tree
Inventory Installed software per host, pending updates, pending security updates
Writes Create hosts (optionally with their agent pull-mode connection), services, templates, commands, contacts and groups; update hosts, services, contacts and contact groups

What makes it more than an API wrapper:

  • Names, never IDs. Every tool takes hostnames, template names and container paths, and resolves them itself.
  • Scope-checked writes. References are validated against the target container before anything is sent - which openITCOCKPIT's own API does not do.
  • Answers shaped for a model. List results carry {items, count, truncated, hint}, so a partial answer cannot be mistaken for a complete one, and a call that omits a required argument is answered with the values that would have worked instead of a validation error.
  • http and stdio transports, MCP annotations and a title on every tool, plus skills/ with tool-chaining recipes for incident triage, host onboarding, patch review and safe configuration changes.

Run it

docker run -d -p 8000:8000 \
  -e MCP_AUTH_TOKEN="a-token-you-generate" \
  -e OITC_APIKEY="the-openITCOCKPIT-api-key" \
  -e OITC_BASEURL="https://openitcockpit.example.org" \
  openitcockpit/mcp-server:0.1.0

Point your client at http://localhost:8000/mcp, using MCP_AUTH_TOKEN as the bearer token. No secret is baked into the image.

Important

The two secrets have different jobs and the server refuses to start if they are equal: clients present MCP_AUTH_TOKEN to this server, and this server presents OITC_APIKEY to openITCOCKPIT. Every client that passes the bearer check acts as the one openITCOCKPIT user that key belongs to - create it for a dedicated, least-privilege user.

Write tools are not even registered unless you set OITC_ENABLE_WRITE_TOOLS=true. The HTTP transport serves plain HTTP: terminate TLS at a reverse proxy, or keep the server on a trusted network.

Note

Pin 0.1.0, don't follow latest. This is 0.x - every tool has been exercised against live instances, but the tool set and its parameters have not yet held still across releases, so a minor bump may still break a client.

What went into it

  • #1 - restructure into a package, with tests and release tooling
  • #2 - simplify release tags to plain semver plus latest
Coming from the unversioned oitc_mcp.py?

The predecessor was published as openitcockpit/mcp-server:5.6.1, an image since removed from Docker Hub. Tool names, response shapes and configuration all changed - the differences that will break a client are listed under Coming from the unversioned oitc_mcp.py in the changelog.


Full tool reference and configuration: README