OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Update version

update_version

Updates a version's name, dates, description, status, or sharing so you can move sprint dates, close a release, or widen sharing for subprojects.

Instructions

Change a version's name, dates, description, status or sharing.

Use it to move a sprint's dates, to close a finished release (status='closed'), or to widen sharing so a subproject can use the version. The change is validated through POST /versions/{id}/form first, so rejected values come back as violations naming the attribute.

Only the parameters you pass are sent, so concurrent edits to other fields survive. Versions carry no lockVersion upstream, so there is nothing to echo and no lock parameter here — a 409 would mean the resource itself changed, not a stale version.

Returns the updated version in the same shape as create_version.

Pitfalls: end_date writes the API's endDate — it lands, unlike in the old server. description REPLACES the stored text. Closing a version does not move or unassign its work packages; they keep pointing at it. The defining project cannot be changed — create a new version instead.

Cross-references: list_versions for ids and current values; delete_version when the version must really disappear; update_work_package(version=...) to move individual work packages between versions.

Input Schema

Name	Required	Description	Default
`name`	No	New name. Omit to leave it alone.
`status`	No	open, locked or closed. Closing a version keeps its work packages but stops new ones being assigned — it is the safe alternative to delete_version. Omit to leave the status alone.
`sharing`	No	none, descendants, hierarchy, tree or system. Narrowing the sharing of a version other projects already use is rejected by the API. Omit to leave it alone.
`end_date`	No	New finish date, ISO YYYY-MM-DD, written to the API's 'endDate'. Pass null to clear it. Omit the parameter to leave it untouched.	__unchanged__
`start_date`	No	New start date, ISO YYYY-MM-DD. Pass null to clear it. Omit the parameter entirely (the default) to leave it untouched.	__unchanged__
`version_id`	Yes	Numeric version id from list_versions or get_project_metadata(project_id=...).versions.
`description`	No	New markdown description; REPLACES the existing text. Pass null or an empty string to clear it. Omit to leave it untouched.	__unchanged__

Output Schema

Name	Required	Description	Default
`id`	No
`name`	No
`source`	No
`status`	No
`project`	No
`sharing`	No
`end_date`	No
`created_at`	No
`start_date`	No
`updated_at`	No
`description`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed42 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"A single version as the write tools return it."

removedOutput schema / properties / created_at / anyOf

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

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

removedOutput schema / properties / description / anyOf

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

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

removedOutput schema / properties / description / description

Removed value: -"Description as markdown (raw); html is dropped."

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

removedOutput schema / properties / end_date / anyOf

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

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

removedOutput schema / properties / end_date / description

Removed value: -"ISO date (YYYY-MM-DD); the version's finish date."

addedOutput schema / properties / end_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: -"Version id — what update_version, delete_version and the work-package 'version' field consume."

addedOutput schema / properties / id / type

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

removedOutput schema / properties / name / anyOf

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

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

removedOutput schema / properties / name / description

Removed value: -"Version name, e.g. 'Sprint 12' or '2.1'."

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

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: -"The project that DEFINES the version. A version shared from a parent project shows that parent here, not the project you asked about."

removedOutput schema / properties / sharing / anyOf

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

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

removedOutput schema / properties / sharing / description

Removed value: -"How far the version is shared: none, descendants, hierarchy, tree, system."

addedOutput schema / properties / sharing / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / source / default
```
Removed value: -"version"
```

removedOutput schema / properties / source / description

Removed value: -"'sprint' when the row came from the backlogs sprints endpoint, 'version' otherwise. Sprints ARE versions upstream, so a row can be both and is then reported as 'sprint'."

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"
+]
```

removedOutput schema / properties / status / anyOf

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

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

removedOutput schema / properties / status / description

Removed value: -"open, locked or closed. Locked and closed versions reject new work package assignments."

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

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.8/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing the POST /versions/{id}/form validation step and the 'violations' error shape, the partial-send semantics that preserve concurrent edits, the deliberate absence of a lockVersion, and the meaning of a 409. It also states what closing does NOT do to work packages and that the defining project is immutable — behavior an agent cannot infer from readOnly/destructive/idempotent hints.

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?

Purpose and use cases are front-loaded, then behavior, then pitfalls and cross-references — a sensible order. It is long, and the pitfall about end_date ('it lands, unlike in the old server') references implementation history the agent does not need.

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?

With an output schema present the description only needs to point at the return value, which it does ('same shape as create_version'), and it covers validation failure, partial-update concurrency, and the immutability boundary. Nothing material for a correct invocation is left out.

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 still adds real value by explaining that only passed parameters are transmitted, that end_date maps to the API's endDate, that description REPLACES stored text, and that narrowing sharing on an in-use version is rejected. Most of the remaining field detail is duplicated from the schema rather than new.

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?

The opening sentence names a specific verb (change) and enumerates the mutable fields of a specific resource (version). The surrounding text makes clear how it differs from create_version, delete_version and update_work_package.

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?

It gives three concrete use cases (move sprint dates, close a finished release, widen sharing) and an explicit cross-reference block routing to list_versions for ids, delete_version when removal is required, and update_work_package(version=...) to move work packages instead.

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

Deploy Server