OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Get project phase

get_project_phase

Read-onlyIdempotent

Retrieve a single project phase record—name, active status, and definition—using a phase ID from a work package's project_phase reference. Confirms which project and definition a phase belongs to.

Instructions

Read one project's phase record: name, active flag and its definition.

Use it after get_work_package surfaced a project_phase reference and you need to know which project and definition that phase belongs to, or whether it is still active.

Returns {id, name, active, definition, project, created_at, updated_at}.

Pitfalls: the API has no phases index — ids only come from work packages' project_phase references. Phase dates are not exposed by the API (the notes say so), so "which projects are in this phase now" goes through list_projects(in_phase=...) instead. A 404 covers a wrong id, a phase invisible to this user (view_project_phases), and instances that predate project phases (16.1).

Cross-references: list_project_phase_definitions for the instance-wide catalog and gates; list_projects(in_phase=...) for date-based phase queries.

Input Schema

Name	Required	Description	Default
`phase_id`	Yes	Per-project phase record id, from a work package's project_phase reference. NOT a definition id from list_project_phase_definitions.

Output Schema

Name	Required	Description	Default
`id`	No
`name`	No
`notes`	No
`active`	No
`project`	No
`created_at`	No
`definition`	No
`updated_at`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed29 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"One project's instance of a phase definition."

removedOutput schema / properties / active / anyOf

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

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

removedOutput schema / properties / active / description

Removed value: -"False when the project switched this phase off."

addedOutput schema / properties / active / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

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

changedOutput schema / properties / definition / 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 / definition / default
```
Removed value: -null
```

removedOutput schema / properties / definition / description

Removed value: -"The instance-global phase definition this instantiates."

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: -"Phase id — a per-project record id, not the definition id."

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: -"Phase name."
```
addedOutput schema / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation notes for this result."

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: -"Project this phase belongs to."
```

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?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantive context: no phases index exists, phase dates are unexposed by the API, and a 404 conflates wrong id, missing permission (view_project_phases), and pre-16.1 instances. That is real behavioral disclosure beyond the structured data.

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 purpose, then usage, return shape, pitfalls, cross-references. Well organized with zero filler prose, though the explicit return-field list is somewhat redundant given an output schema exists.

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 a single parameter, an output schema, and rich annotations, the remaining risks (where ids come from, what a 404 means, which sibling answers date-based questions) are all covered. 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% and the schema already says it is a per-project phase record id from a work package reference, not a definition id. The description reinforces the sourcing constraint ('ids only come from work packages' project_phase references'), adding marginal value beyond the schema rather than new syntax detail.

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 ('Read one project's phase record') plus the exact returned fields, and explicitly separates itself from list_project_phase_definitions in Cross-references. An agent can distinguish it from the catalog-listing sibling without opening either 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?

Gives an explicit trigger ('after get_work_package surfaced a project_phase reference'), names the alternative for the adjacent question ('which projects are in this phase now' goes through list_projects(in_phase=...)'), and explains the 404 conditions. When-to-use and when-not-to-use are both covered.

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

Deploy Server