OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List project phase definitions

list_project_phase_definitions

Read-onlyIdempotent

List instance-global project phase definitions to discover available phases and gates, and get the phase id or name used by project listing filters.

Instructions

List the instance-global phase definitions — the vocabulary of the project life cycle.

Use it to learn which phases (Initiating, Planning, …) and gates this instance defines, and to get the definition id or name that list_projects(in_phase=...) accepts.

Returns the standard list envelope of {id, name, start_gate, start_gate_name, finish_gate, finish_gate_name} rows. Gates are the checkpoints a phase can begin or end with; a definition without gates has both flags false.

Pitfalls: definitions are the instance-wide catalog, not any project's actual phases — a project may deactivate phases or set no dates. Phase dates are not exposed by the API at all. Requires OpenProject 16.1+ and the view_project_phases permission in at least one project; older instances 404 (the error hint says so).

Cross-references: list_projects(in_phase=...) to find the projects a phase covers today; get_project_phase for one project's phase record (its id comes from a work package's project_phase).

Input Schema

Name	Required	Description	Default
`page`	No	1-based page number.
`page_size`	No	Records per page (max 100); most instances define fewer than a page of phases.

Output Schema

Name	Required	Description	Default
`sums`	No
`items`	No
`notes`	No
`groups`	No
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed38 schema fields changedv0.4.0Oct 24, 2026

changedOutput schema / properties / groups / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A server-side group bucket, computed over the full filtered set.",
-      "properties": {
-        "count": {
-          "default": 0,
-          "description": "Records in this group across all pages.",
-          "type": "integer"
-        },
-        "sums": {
-          "anyOf": [
-            {
-              "additionalProperties": {
-                "type": "number"
-              },
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Per-group sums when show_sums was requested."
-        },
-        "value": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Group value, e.g. a status name."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "sums": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "number"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

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

removedOutput schema / properties / groups / description

Removed value: -"Present only when group_by was requested."

removedOutput schema / properties / items / description
```
Removed value: -"The page of results."
```

removedOutput schema / properties / items / items / description

Removed value: -"One instance-global project phase definition, with its gates."

removedOutput schema / properties / items / items / properties / finish_gate / anyOf

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

removedOutput schema / properties / items / items / properties / finish_gate / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / finish_gate / description
```
Removed value: -"True when the phase ends with a gate."
```
addedOutput schema / properties / items / items / properties / finish_gate / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / finish_gate_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / finish_gate_name / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / finish_gate_name / description
```
Removed value: -"Display name of the finish gate; null without one."
```
addedOutput schema / properties / items / items / properties / finish_gate_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / id / anyOf

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

removedOutput schema / properties / items / items / properties / id / default
```
Removed value: -null
```

removedOutput schema / properties / items / items / properties / id / description

Removed value: -"Definition id — the value list_projects' in_phase accepts."

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

removedOutput schema / properties / items / items / properties / name / anyOf

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

removedOutput schema / properties / items / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / name / description
```
Removed value: -"Phase name, e.g. 'Executing'."
```
addedOutput schema / properties / items / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / start_gate / anyOf

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

removedOutput schema / properties / items / items / properties / start_gate / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / start_gate / description
```
Removed value: -"True when the phase begins with a gate."
```
addedOutput schema / properties / items / items / properties / start_gate / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / start_gate_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / start_gate_name / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / start_gate_name / description
```
Removed value: -"Display name of the start gate; null without one."
```
addedOutput schema / properties / items / items / properties / start_gate_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation markers: capped aggregations, unavailable modules, …"

removedOutput schema / properties / pagination / description
```
Removed value: -"Total/page/page_size/has_more."
```
removedOutput schema / properties / pagination / properties / has_more / description
```
Removed value: -"True when further pages exist."
```
removedOutput schema / properties / pagination / properties / page / description
```
Removed value: -"1-based page number of this result."
```
removedOutput schema / properties / pagination / properties / page_size / description
```
Removed value: -"Records requested per page."
```
removedOutput schema / properties / pagination / properties / total / description
```
Removed value: -"Total matching records on the server."
```
removedOutput schema / properties / sums / default
```
Removed value: -null
```

removedOutput schema / properties / sums / description

Removed value: -"Present only when show_sums was requested."

First observedv0.1.0Aug 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses the return envelope shape, the meaning of start/finish gates (false flags = no gates), a version requirement (OpenProject 16.1+, 404 on older instances with a matching error hint), a required permission (view_project_phases in at least one project), and the important limitation that phase dates aren't exposed by the API at all.

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, then labeled Pitfalls and Cross-references sections — easy to scan and every block carries distinct information. It runs slightly long relative to a two-parameter list tool, but little of it is 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?

Covers everything an agent needs: what it returns, what gates mean, version and permission prerequisites, the failure mode on old instances, and how to follow up with sibling tools. With an output schema present, restating the envelope is a bonus rather than a gap.

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 coverage is 100% and both parameters (page, page_size) are fully documented in the schema, including the max-100 limit and the note that most instances define fewer than a page. The description adds no additional parameter guidance, so the baseline 3 applies.

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 ('List the instance-global phase definitions') and immediately clarifies scope with 'the vocabulary of the project life cycle.' It explicitly distinguishes the catalog from a project's actual phases and from get_project_phase, which shares the domain.

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 purpose for calling it (learn which phases/gates exist, get the id/name that list_projects(in_phase=...) accepts) and routes to the two relevant alternatives — list_projects(in_phase=...) for coverage today and get_project_phase for one project's record.

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

Deploy Server