OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List permissions

list_permissions

Read-onlyIdempotent

Check what the authenticated user is allowed to do globally or in a specific project before attempting writes or explaining permission-related failures.

Instructions

List what the authenticated user is allowed to do, globally or in one project.

Use it before attempting a write that might 403, to explain to a user why an action failed, or to pick between tools ("can I add a member here, or should I ask an admin?"). It reads the real capabilities API for the current user — it does not return a user profile and it never guesses from the admin flag.

Returns the standard list envelope whose items are one row per context — {id, context, project, actions} with actions such as work_packages/create — plus principal (the user asked about), capability_count, and check when permission was given.

CAVEAT, straight from the API: OpenProject exposes only a SUBSET of its permissions as capabilities. An action missing from this list is not proof that the user lacks the permission — it may simply not be modelled. Treat a hit as reliable and a miss as "unknown, try it and read the 403".

Pitfalls: the capabilities API has no "me" value, so the numeric id of the authenticated user is resolved first (from the cached users/me) — you cannot ask about another user with this tool. Results are capped at 500 capabilities with a note in notes when the cap is hit; scope with project_id to stay well under it. Capabilities are about permission only: a permitted action can still fail validation.

Cross-references: get_instance_info reports who this server is authenticated as and what the instance version supports; list_memberships and list_roles show where the permissions come from; get_project_metadata lists the ids a permitted action needs.

Input Schema

Name	Required	Description	Default
`permission`	No	Optional single action to check, spelled the way OpenProject does: '<resource>/<action>', e.g. 'work_packages/create', 'memberships/create', 'projects/update'. Adds a {checked, allowed, granted_in} predicate to the result; the full grouped listing is returned either way, so you can see the exact spellings this instance uses.
`project_id`	No	Numeric project id or URL identifier to scope the question to that project ('may I create work packages HERE'). Omit it for the instance-wide (global) actions such as creating projects or administering users. An identifier is resolved to its numeric id first, because the capabilities API only accepts numeric project ids.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed35 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"The standard list envelope of capability rows, plus who was asked about and the check."

removedOutput schema / properties / capability_count / default
```
Removed value: -0
```

removedOutput schema / properties / capability_count / description

Removed value: -"Individual capabilities read from the API before grouping."

changedOutput schema / properties / check / anyOf

Previous value: -[
-  {
-    "description": "The answer to the optional ``permission`` predicate.",
-    "properties": {
-      "allowed": {
-        "description": "True when the action appears in the capabilities listed here. False means 'not listed' — see the tool's caveat, it is not proof of a denial.",
-        "type": "boolean"
-      },
-      "checked": {
-        "description": "The permission string that was checked, as normalized.",
-        "type": "string"
-      },
-      "granted_in": {
-        "description": "Ids of the CapabilityGroup rows that carry the action; empty when not found.",
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "checked",
-      "allowed"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "allowed": {
+        "type": "boolean"
+      },
+      "checked": {
+        "type": "string"
+      },
+      "granted_in": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "checked",
+      "allowed"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

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

removedOutput schema / properties / check / description

Removed value: -"Present only when the 'permission' parameter was given."

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: -"The actions the current user may perform in one context."

removedOutput schema / properties / items / items / properties / actions / description

Removed value: -"Action names as OpenProject spells them, e.g. 'memberships/create', 'work_packages/read'. Sorted; always a list."

removedOutput schema / properties / items / items / properties / context / description

Removed value: -"'global' for instance-wide actions, 'project' for actions inside one project."

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

Removed value: -"Stable row id: 'global' or 'project:<id>'. Also the grouping key."

changedOutput schema / properties / items / items / 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 / items / items / properties / project / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / project / description
```
Removed value: -"The project this row is about; null for the global context."
```
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 / principal / description

Removed value: -"The user the capabilities were resolved for — always the authenticated account, by numeric id."

removedOutput schema / properties / principal / properties / id / anyOf

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

removedOutput schema / properties / principal / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / principal / properties / id / description
```
Removed value: -"Resource id."
```
addedOutput schema / properties / principal / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```

removedOutput schema / properties / principal / properties / name / anyOf

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

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

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds material context beyond that: the capabilities API exposes only a subset of permissions, so a miss means "unknown" rather than "denied"; results cap at 500 with a note; and the implicit user-id resolution from cached users/me. It stops short of describing error shape, but the trust model for hits vs. misses is the important disclosure and it is present.

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?

Long but deliberately sectioned — purpose, return shape, caveat, pitfalls, cross-references — with the core statement front-loaded and no filler sentences. The density is justified by real caveats, though it is heavier than strictly necessary for a two-parameter read tool.

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?

Output schema exists and the description still sketches the envelope (items, principal, capability_count, check) enough to orient the agent. Combined with annotations covering safety, the description leaves no gap that would cause a wrong invocation or a wrong interpretation of an empty result.

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, but the description adds real semantics: project_id scoping is the mitigation for the 500 cap, omitting it means instance-wide actions, and permission adds a predicate while the grouped listing is still returned. That goes beyond the schema's per-parameter text.

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?

Opens with a specific verb+resource+scope: "List what the authenticated user is allowed to do, globally or in one project." It also explicitly excludes a plausible misreading ("it does not return a user profile") and names how it differs from get_instance_info, list_memberships and list_roles.

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 three concrete triggering situations (before a write that might 403, explaining a failure, choosing between tools) plus an explicit pitfall: you cannot query another user with this tool. The cross-references section routes the agent to the right sibling for identity, provenance and ids.

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

Deploy Server