## Tool: `list_principals`

Lists the principals (users) that have access to a specific merchant. This operation requires Admin access for the merchant.

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

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

## Input Schema

Request message for listing the principals of a merchant.

### ListPrincipalsRequest

| JSON representation |
|---|
| ``` { "merchantId": string } ``` |

| Fields ||
|---|---|
| `merchantId` | `string` Required. The merchant id, for which to list principals. |

## Output Schema

Response message for listing the principals of a merchant.

### ListPrincipalsResponse

| JSON representation |
|---|
| ``` { "principals": [ { object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/list_principals#Output.Schema.Principal`) } ] } ``` |

| Fields ||
|---|---|
| `principals[]` | ``object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/list_principals#Output.Schema.Principal`)`` The principals that have access to the merchant. |

### Principal

| JSON representation |
|---|
| ``` { "email": string, "displayName": string, "role": enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/list_principals#Output.Schema.PrincipalRole`), "state": enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/list_principals#Output.Schema.State`) } ``` |

| Fields ||
|---|---|
| `email` | `string` Required. The email address of the principal. |
| `displayName` | `string` Output only. The display name of the principal. |
| `role` | ``enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/list_principals#Output.Schema.PrincipalRole`)`` The role of the principal on the merchant. |
| `state` | ``enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/list_principals#Output.Schema.State`)`` Output only. The access state of the principal on the merchant. |

### PrincipalRole

A role that can be granted to a principal (user) on a merchant.

| Enums ||
|---|---|
| `PRINCIPAL_ROLE_UNSPECIFIED` | The role is unspecified. |
| `ADMIN` | Full access to the merchant, including managing users. |
| `DEVELOPER` | Access intended for developers integrating with the merchant. |

### State

The state of a principal's access on a merchant.

| Enums ||
|---|---|
| `STATE_UNSPECIFIED` | The access state is unspecified. |
| `ACTIVE` | The principal has an active, accepted access. |
| `PENDING` | The principal has been invited but has not accepted the invitation yet. |
| `EXPIRED` | The principal's invitation has expired. |

### 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: ❌