## Tool: `list_memberships`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

Lists memberships in a Google Chat conversation.

The following code sample shows how to use `curl` to call the `list_memberships` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://chatmcp.googleapis.com/mcp/v1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "list_memberships", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

### ListMembershipsRequest

| JSON representation |
|---|
| ``` { "conversationId": string, "pageSize": integer, "pageToken": string, "membershipFilter": enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Input.Schema.MembershipFilter`) } ``` |

| Fields ||
|---|---|
| `conversationId` | `string` Required. The ID of the conversation to list memberships for. Format: spaces/{space} |
| `pageSize` | `integer` Optional. The maximum number of memberships to return. The service may return fewer than this value. If unspecified or set to a non-positive value, a default value of 20 is used. The maximum allowed value is 50. |
| `pageToken` | `string` Optional. A page token, received from a previous list_memberships call. Provide this to retrieve the subsequent page. |
| `membershipFilter` | ``enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Input.Schema.MembershipFilter`)`` Optional. Specifies the subset of memberships to return. If unspecified, only JOINED memberships are returned. |

### MembershipFilter

Specifies the subset of memberships to return.

| Enums ||
|---|---|
| `MEMBERSHIP_FILTER_UNSPECIFIED` | Default value. If unspecified, returns only JOINED memberships. |
| `JOINED_ONLY` | Returns only JOINED memberships. |
| `JOINED_AND_INVITED` | Returns JOINED and INVITED memberships. |

## Output Schema

Response containing the list of memberships in the conversation.

### ListMembershipsResponse

| JSON representation |
|---|
| ``` { "memberships": [ { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Output.Schema.Membership`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `memberships[]` | ``object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Output.Schema.Membership`)`` List of memberships in the requested conversation. |
| `nextPageToken` | `string` A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |

### Membership

| JSON representation |
|---|
| ``` { "member": { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.User`) }, "state": enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Output.Schema.State`), "role": enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Output.Schema.Role`) } ``` |

| Fields ||
|---|---|
| `member` | ``object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.User`)`` The user that is a member. |
| `state` | ``enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Output.Schema.State`)`` Output only. State of the membership. |
| `role` | ``enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_memberships#Output.Schema.Role`)`` Role of the member. |

### User

| JSON representation |
|---|
| ``` { "userId": string, "displayName": string, "email": string, "userType": enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.UserType`) } ``` |

| Fields ||
|---|---|
| `userId` | `string` Resource name of a Chat user. Format: users/{user}. |
| `displayName` | `string` The display name of a Chat user. |
| `email` | `string` The email address of the user. This field is only populated when the user type is HUMAN. |
| `userType` | ``enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.UserType`)`` The type of the user. |

### UserType

The type of a Google Chat user.

| Enums ||
|---|---|
| `USER_TYPE_UNSPECIFIED` | Unspecified. |
| `HUMAN` | Human user. |
| `APP` | App user. |

### State

State of the membership.

| Enums ||
|---|---|
| `STATE_UNSPECIFIED` | Unspecified. |
| `JOINED` | The user is a member of the space. |
| `INVITED` | The user is invited to join the space. |

### Role

Role of the member.

| Enums ||
|---|---|
| `ROLE_UNSPECIFIED` | Unspecified. |
| `MEMBER` | The user is a member of the space. |
| `MANAGER` | The user is a manager of the space. |
| `ASSISTANT_MANAGER` | The user is an assistant manager of the space. |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ \| Idempotent Hint: ✅ \| Read Only Hint: ✅ \| Open World Hint: ❌

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/chat.memberships`
- `https://www.googleapis.com/auth/chat.memberships.readonly`