OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List project memberships

list_memberships

Read-onlyIdempotent

List project memberships and roles to audit access, check whether a principal already has a role, or identify which projects a user can reach before granting or revoking permissions.

Instructions

List who has access to which project, and with which roles.

Use it before granting or revoking access ("does she already have a role here?"), to audit a project's member list, or to see which projects a principal can reach. Called with no arguments it pages through every membership the authenticated account may see, which on a large instance is a lot — filter.

Returns the standard list envelope: items of {id, project, principal {id,name,type}, roles[], created_at, updated_at} plus pagination{total,page,page_size,has_more}.

Pitfalls. The id in each row is the membership id — the handle for update_membership and delete_membership — not the principal id and not the project id; mixing them up revokes the wrong access. A person can also reach a project through a group membership, so an empty result for principal_id does not prove they have no access. Memberships say who may act, not what they may do: roles carry the permissions.

Cross-references: list_roles for role ids and their permissions; create_membership / update_membership / delete_membership to change access (admin-gated: hidden unless the server sets OPENPROJECT_MCP_ADMIN_TOOLS=1); search_principals for principal ids; list_permissions for what the current user may do.

Input Schema

Name	Required	Description
`page`	No	1-based page number.
`page_size`	No	Memberships per page, 1-100.
`project_id`	No	Only memberships in this project. Numeric id or the URL identifier (an identifier costs one extra lookup). Combine with principal_id to check one person's roles in one project.
`principal_id`	No	Only memberships held by this principal — a user, group or placeholder-user id from search_principals. Use it to answer 'which projects can this person see'.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed44 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 project membership: a principal holding roles in a project."

removedOutput schema / properties / items / items / properties / created_at / anyOf

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

removedOutput schema / properties / items / items / properties / created_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / created_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / items / items / properties / created_at / 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: -"Membership id. Pass it to update_membership or delete_membership; it is not the principal id and not the project id."

addedOutput schema / properties / items / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / items / items / properties / notes / description

Removed value: -"Markers about what this call did, e.g. notifications suppressed."

changedOutput schema / properties / items / items / properties / principal / anyOf

Previous value: -[
-  {
-    "description": "A principal reference that keeps its kind — used inside memberships.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Principal id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Display name."
-      },
-      "type": {
-        "anyOf": [
-          {
-            "enum": [
-              "user",
-              "group",
-              "placeholder"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "'user', 'group' or 'placeholder'; null when the instance did not say."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "type": {
+        "anyOf": [
+          {
+            "enum": [
+              "user",
+              "group",
+              "placeholder"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / principal / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / principal / description
```
Removed value: -"Who holds the membership: user, group or placeholder user."
```

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: -"Project the membership grants access to."
```

removedOutput schema / properties / items / items / properties / roles / description

Removed value: -"Roles held in this project; always a list. Role ids come from list_roles."

removedOutput schema / properties / items / items / properties / roles / items / description
```
Removed value: -"A reference to another resource. Canonical output shape."
```

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

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

removedOutput schema / properties / items / items / properties / roles / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / roles / items / properties / id / description
```
Removed value: -"Resource id."
```
addedOutput schema / properties / items / items / properties / roles / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / roles / items / properties / name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / roles / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / roles / items / properties / name / description
```
Removed value: -"Human-readable name."
```
addedOutput schema / properties / items / items / properties / roles / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / updated_at / anyOf

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

removedOutput schema / properties / items / items / properties / updated_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / updated_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / items / items / properties / updated_at / 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral context: the return envelope shape, the pitfall that row `id` is a membership id (mixing it up revokes the wrong access), that group memberships can mask access, and that admin tools are gated behind an env flag.

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 usage, return shape, pitfalls, and cross-references in clearly labeled blocks. Every section is useful, though the return-envelope paragraph is somewhat long 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?

Covers everything an agent needs: when to call, what comes back, the id-confusion trap, the group-membership blind spot, and the role-vs-permission distinction. A mutation-adjacent read tool with this much nuance is fully described.

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 each parameter already documents its id semantics and cross-references search_principals. The description's 'filter' advice and the project_id+principal_id combination are already present in the schema, so it adds little beyond baseline.

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 who has access to which project, and with which roles') and immediately clarifies the scope (membership, not permissions). It is clearly distinguishable from sibling read tools like list_projects or 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?

Explicit when-to-use cases are given (pre-grant/revoke checks, auditing, reachability), plus a warning that an unfiltered call pages through everything and should be filtered. Alternatives are named for role ids, principal ids, and mutations.

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

Deploy Server