OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Execute custom action

execute_custom_action

Run an administrator-defined one-click action on a work package to apply multiple field changes at once, returning the updated work package row.

Instructions

Run an instance-defined one-click action on a work package.

Custom actions are shortcuts an administrator configured — "Accept and assign to me", "Reject", "Move to review" — that apply several field changes at once, sometimes under conditions (role, status, project). Use one when get_work_package(include=['custom_actions']) offers it, instead of reproducing its effects field by field. Returns the updated work package row (subject, type, status, priority, assignee, project, dates, percentage_done, updated_at).

Pitfalls. The action decides what changes; this tool cannot influence it, and OpenProject does not report which fields it touched — compare the returned row with what you read before, or call get_work_package again for the full detail (including the new lock_version for your next update). Availability is per work package: an action listed on one ticket may 403 on another because its conditions no longer hold, and a 422 usually means the resulting work package would be invalid (a required field the action leaves empty). Writes are never retried automatically — a conflict comes back with the fresh lock_version so you can re-read and decide.

Cross-references: get_work_package(include=['custom_actions']) produces the ids and says which are available right now; update_work_package is the explicit alternative when you know exactly which fields to set; list_work_package_comments shows what the action recorded in the journal.

Input Schema

Name	Required	Description
`lock_version`	No	The work package's current lockVersion, from get_work_package. Omit it and the current value is read first — safe, one extra request. A stale value returns a conflict carrying the fresh one.
`work_package_id`	Yes	Work package to run the action on. It must be the one the action was listed for; conditions are re-checked server-side.
`custom_action_id`	Yes	Id of the custom action to run. Get it from get_work_package(id=..., include=['custom_actions']), which lists the actions this instance defines AND this work package currently qualifies for — the names are instance-specific, so never guess an id.

Output Schema

Name	Required	Description	Default
`id`	No
`type`	No
`status`	No
`project`	No
`subject`	No
`assignee`	No
`due_date`	No
`priority`	No
`display_id`	No
`start_date`	No
`updated_at`	No
`percentage_done`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed44 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"Compact work-package row for list results."

changedOutput schema / properties / assignee / 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 / assignee / default
```
Removed value: -null
```
removedOutput schema / properties / assignee / description
```
Removed value: -"Assigned user or group."
```

removedOutput schema / properties / display_id / anyOf

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

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

removedOutput schema / properties / display_id / description

Removed value: -"Human-facing id as the instance renders it. Matches the numeric id unless the instance uses semantic identifiers (17.x, e.g. 'PROJ-42'); null when the instance predates it."

addedOutput schema / properties / display_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / due_date / anyOf

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

removedOutput schema / properties / due_date / default
```
Removed value: -null
```
removedOutput schema / properties / due_date / description
```
Removed value: -"ISO date (YYYY-MM-DD)."
```
addedOutput schema / properties / due_date / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / id / anyOf

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

removedOutput schema / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / id / description
```
Removed value: -"Work package id."
```

addedOutput schema / properties / id / type

Added value: +[
+  "integer",
+  "string",
+  "null"
+]

removedOutput schema / properties / percentage_done / anyOf

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

removedOutput schema / properties / percentage_done / default
```
Removed value: -null
```
removedOutput schema / properties / percentage_done / description
```
Removed value: -"Progress, 0-100."
```
addedOutput schema / properties / percentage_done / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

changedOutput schema / properties / priority / 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 / priority / default
```
Removed value: -null
```
removedOutput schema / properties / priority / description
```
Removed value: -"Priority."
```

changedOutput schema / properties / project / 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 / project / default
```
Removed value: -null
```
removedOutput schema / properties / project / description
```
Removed value: -"Owning project."
```

removedOutput schema / properties / start_date / anyOf

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

removedOutput schema / properties / start_date / default
```
Removed value: -null
```
removedOutput schema / properties / start_date / description
```
Removed value: -"ISO date (YYYY-MM-DD)."
```
addedOutput schema / properties / start_date / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / status / 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 / status / default
```
Removed value: -null
```
removedOutput schema / properties / status / description
```
Removed value: -"Status."
```

removedOutput schema / properties / subject / anyOf

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

removedOutput schema / properties / subject / default
```
Removed value: -null
```
removedOutput schema / properties / subject / description
```
Removed value: -"Subject line."
```
addedOutput schema / properties / subject / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / type / 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 / type / default
```
Removed value: -null
```
removedOutput schema / properties / type / description
```
Removed value: -"Work package type."
```

removedOutput schema / properties / updated_at / anyOf

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

removedOutput schema / properties / updated_at / default
```
Removed value: -null
```
removedOutput schema / properties / updated_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / updated_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```

First observedv0.1.0Aug 12, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Adds substantial context beyond annotations: the action itself decides which fields change, the server does not report touched fields, and callers should compare the returned row or re-fetch. It also explains likely 403/422 outcomes, that writes are not auto-retried, and that conflicts return a fresh ``lock_version``.

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

Conciseness5/5

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

Despite its length, the description is front-loaded, paragraph-structured, and each section earns its place: purpose, usage, return shape, pitfalls, and cross-references. There is no filler.

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?

For a non-idempotent write with an output schema and detailed annotations, the description supplies the operational caveats an agent needs: action availability, server-side conditions, conflict handling, and field-change opacity. Nothing material is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the parameter meanings are already fully documented in the schema. The description reinforces that ``custom_action_id`` must come from ``get_work_package`` and that availability is per work package, but does not add much parameter-specific detail beyond the schema.

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: "Run an instance-defined one-click action on a work package." It also distinguishes the tool from siblings by naming ``update_work_package`` as the explicit field-by-field alternative.

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?

Gives clear when-to-use guidance: use it when ``get_work_package(include=['custom_actions'])`` offers the action rather than reproducing its effects manually. It also names the alternative ``update_work_package`` for cases where the exact fields are known.

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

Deploy Server