Repository navigation
Releases
v0.5.0
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-modelThe 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_hosttemplateandcreate_servicetemplateenable notifications. The payload leftnotifications_enabledout, 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.
descput 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_containerno longer needsOITC_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.0Note
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
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 forIn 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_APIKEYmust 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 jsonprints 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_treewithout a name starts at the top-most containers the account can see. A user limited to tenants cannot see root and gotNo 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.0Important
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
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 defaultA 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 -dTools
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.0Note
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
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-promptfiles 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-onboardingandoitc-config-changeare registered only whenOITC_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.jsonin the repo root carries the entry, validated against the2025-12-11schema.- The image carries an
io.modelcontextprotocol.server.namelabel, which the registry reads off the published image as its only ownership proof for an OCI package.0.1.0carried no labels at all. - The declared transport is
stdio: a client that runs this container itself has neither a published port nor anMCP_AUTH_TOKEN, so the declared environment defaults saystdiotoo.
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.0Note
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
v0.1.0
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. httpandstdiotransports, MCP annotations and a title on every tool, plusskills/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.0Point 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