OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Create version

create_version

Create a version (release, milestone or sprint) in a project to plan sprints or releases before assigning work packages. Duplicate names or invalid date ranges return named violations instead of opaque errors.

Instructions

Create a version (release, milestone or sprint) inside a project.

Use it to open a new sprint or plan a release before assigning work packages to it. The call goes through POST /versions/form first, so a duplicate name or an impossible date range comes back as violations naming the attribute instead of an opaque rejection.

Returns the created version {id, name, project, status, start_date, end_date, description, sharing, source, created_at, updated_at}. The id is what update_work_package(version=...) and update_version consume.

Pitfalls: end_date is the version's finish date and is written to the API's endDate field — passing a date here always lands (an older client dropped it silently). Creating versions needs the 'manage versions' permission in the project, so a 403 is about the account, not the payload. Versions are per project: sharing is the only way another project sees this one.

Cross-references: list_versions for what already exists (and for the ids); update_version to change dates or close it later; list_projects for the project id.

Input Schema

Name	Required	Description
`name`	Yes	Version name, e.g. 'Sprint 12' or 'Release 2.1'. Must be unique inside the defining project.
`status`	No	open (default upstream), locked or closed. Locked and closed versions cannot receive new work packages, so create with 'open' unless you are recording history.
`sharing`	No	Which other projects may use this version: none (default), descendants, hierarchy, tree or system (the whole instance). Use 'descendants' for a release shared with subprojects.
`end_date`	No	ISO date (YYYY-MM-DD) the version finishes — this is the version's due date, sent as the API's 'endDate'. Omit for none.
`project_id`	Yes	Numeric id or identifier of the project that will DEFINE the version. Sharing decides which other projects can use it; the defining project cannot be changed afterwards.
`start_date`	No	ISO date (YYYY-MM-DD) the version starts. Omit for none.
`description`	No	Markdown description of the version's scope. Omit for none.

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

Behavior3/5

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

Annotations already declare write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety profile is covered. The description still adds real value: the POST /versions/form preflight that surfaces 'violations', the 'manage versions' permission and what a 403 means, and the per-project scoping of sharing. That is solid added context beyond the annotations, though return-format detail is already handled by the output schema.

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 with the core action and then organized into labelled paragraphs (return shape, pitfalls, cross-references), which is easy to scan. It is longer than necessary because the end_date pitfall and return fields are restated in both the description and the 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?

For a non-idempotent, open-world write tool with 7 parameters, the description covers permissions, failure semantics (violations vs opaque rejection), scoping rules and follow-up tools. With an output schema present, return values are additionally stated but not required, so nothing an agent needs to call this correctly is missing.

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 earns an extra point by adding semantics the schema cannot express, such as end_date landing on the API's endDate field after an older client silently dropped it, and that the defining project cannot be changed afterwards. It also repeats some schema content (open vs locked/closed), which caps it below 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 ('Create a version') and immediately disambiguates the resource as 'release, milestone or sprint' inside a project. This distinguishes it cleanly from siblings like list_versions, update_version and delete_version.

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 an explicit when-to-use ('open a new sprint or plan a release before assigning work packages') and routes the agent to alternatives: list_versions for existing ids, update_version to change dates or close, list_projects for the project id. Nothing is left to inference.

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

Deploy Server