List project memberships
list_membershipsIdentify which users, groups, or placeholders have access to a project and their roles; filter by project or principal to audit access.
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 | Default |
|---|---|---|---|
| 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 | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |