OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Add work package watcher

add_work_package_watcher

Idempotent

Subscribe a user to a work package's notifications so they receive updates on comments and changes without being assigned to the ticket.

Instructions

Subscribe a user to a work package's notifications.

Use this when someone should be kept in the loop on a ticket without being assigned to it. Watchers receive OpenProject's notifications for comments and changes. Returns the watcher (user id and name), the watch state after the call, and whether this call actually changed anything.

Pitfalls. The user must already be able to see the work package; OpenProject answers 422 with a violation on user otherwise, and adding someone other than yourself needs the add-work-package-watchers permission (adding yourself only needs view access). Calling twice is harmless: the second call reports changed: false. Watching is not assignment — use update_work_package(assignee=...) for that.

Cross-references: get_work_package(include=['watchers']) lists who already watches; remove_work_package_watcher is the reverse; list_work_package_comments shows what watchers are being notified about.

Input Schema

Name	Required	Description	Default
`user_id`	Yes	Numeric id of the user to add. Get it from list_users, from get_instance_info for the current user, or from any Ref in a work-package result. The string 'me' is not accepted here — the API needs a real id.
`work_package_id`	Yes	Work package to watch. Ids come from search_work_packages, list_work_packages or get_work_package.

Output Schema

Name	Required	Description	Default
`user`	No
`changed`	No
`message`	Yes
`watching`	Yes
`work_package_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"Outcome of adding or removing one watcher."

removedOutput schema / properties / changed / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / changed / default
```
Removed value: -null
```

removedOutput schema / properties / changed / description

Removed value: -"True when this call actually changed the watcher list, false when the user was already watching. Null when OpenProject does not report it — removals answer 204 whether or not the user was watching."

addedOutput schema / properties / changed / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```
removedOutput schema / properties / message / description
```
Removed value: -"Human-readable confirmation."
```

changedOutput schema / properties / user / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / user / default
```
Removed value: -null
```

removedOutput schema / properties / user / description

Removed value: -"The watcher. 'id' is the user id; 'name' is filled in only when OpenProject returned the user resource (it does on add, not on remove)."

removedOutput schema / properties / watching / description

Removed value: -"Watch state after the call: true after adding, false after removing."

removedOutput schema / properties / work_package_id / description

Removed value: -"Work package whose watcher list was changed."

First observedv0.1.0Aug 12, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: discloses the 422 error and the 'user' violation when the target can't see the work package, the differing permission requirements for adding yourself vs others, and the idempotent 'changed: false' behavior on repeat calls. It also describes the return payload (watcher id/name, watch state, changed flag) even though an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by labeled sections (Pitfalls, Cross-references) that make scanning easy, and every sentence carries actionable content. It is on the long side and some return-value detail is slightly redundant with the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, preconditions, permission model, idempotency, error modes, and neighbors — everything needed to call a two-parameter mutation correctly. Return values are explained even though the output schema already carries them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds meaning by tying user_id validity to visibility of the work package and permission scope. It doesn't add id-format or type details beyond the schema, so it doesn't reach 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Subscribe a user to a work package's notifications') and immediately distinguishes it from assignment ('Watching is not assignment'). An agent can tell it apart from update_work_package or remove_work_package_watcher without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('when someone should be kept in the loop... without being assigned'), explicit alternative ('use update_work_package(assignee=...) for that'), and cross-references to the reverse tool and to get_work_package(include=['watchers']) for checking existing watchers.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server