MCP Tools Reference: iam.googleapis.com

Tool: delete_role

Deletes a custom IAM role, making it inactive. Organizations are not supported.

Use this tool to remove a role that is no longer needed.

After a role is deleted, it can no longer be used for new role bindings, and existing bindings utilizing this role will no longer grant any access. This is a destructive operation, although a deleted role can be restored using the undelete_role tool within 7 days.

Predefined roles cannot be deleted.

This tool requires the following parameters:

  • name (string): The resource name of the role to delete. Only projects are supported. The format is projects/PROJECT_ID/roles/ROLE_ID.

The following parameters are optional:

  • etag (string): Base64-encoded etag value for optimistic concurrency control to prevent overwriting concurrent changes.

This tool returns the details of the role that was deleted.

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

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

Input Schema

The request to delete an existing role.

DeleteRoleRequest

JSON representation 
{
  "name": string,
  "etag": string
}
Fields
name

string

The name parameter's value depends on the target resource for the request, namely projects or organizations. Each resource type's name value format is described below:

  • projects.roles.delete: projects/{PROJECT_ID}/roles/{CUSTOM_ROLE_ID}. This method deletes only custom roles that have been created at the project level. Example request URL: https://iam.googleapis.com/v1/projects/{PROJECT_ID}/roles/{CUSTOM_ROLE_ID}

  • organizations.roles.delete: organizations/{ORGANIZATION_ID}/roles/{CUSTOM_ROLE_ID}. This method deletes only custom roles that have been created at the organization level. Example request URL: https://iam.googleapis.com/v1/organizations/{ORGANIZATION_ID}/roles/{CUSTOM_ROLE_ID}

Note: Wildcard (*) values are invalid; you must specify a complete project ID or organization ID.
etag

string (bytes format)

Used to perform a consistent read-modify-write.

A base64-encoded string.

Output Schema

A role in the Identity and Access Management API.

Role

JSON representation 
{
  "name": string,
  "title": string,
  "description": string,
  "includedPermissions": [
    string
  ],
  "stage": enum (RoleLaunchStage),
  "etag": string,
  "deleted": boolean
}
Fields
name

string

The name of the role.

When Role is used in CreateRole, the role name must not be set.

When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
title

string

Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.
description

string

Optional. A human-readable description for the role.
includedPermissions[]

string

The names of the permissions this role grants when bound in an IAM policy.
stage

enum (RoleLaunchStage)

The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
etag

string (bytes format)

Used to perform a consistent read-modify-write.

A base64-encoded string.
deleted

boolean

The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.

RoleLaunchStage

A stage representing a role's lifecycle phase.

Enums
ALPHA The user has indicated this role is currently in an Alpha phase. If this launch stage is selected, the stage field will not be included when requesting the definition for a given role.
BETA The user has indicated this role is currently in a Beta phase.
GA The user has indicated this role is generally available.
DEPRECATED The user has indicated this role is being deprecated.
DISABLED This role is disabled and will not contribute permissions to any principals it is granted to in policies.
EAP The user has indicated this role is currently in an EAP phase.

Tool Annotations

Tool annotations 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: ❌