# IAM MCP Tools

> The MCP tools the SOAT server exposes for the IAM module, with the arguments each tool takes.

# IAM

MCP tools for the IAM module. See the [IAM module docs](/docs/modules/iam) for permissions and data model.

### `check-iam-permission`

Check a permission of the calling credential

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `action` | `string` | yes | A `module:Operation` action the deployment registered or a built-in one (`agents:DeleteAgent`); an unknown action or a wildcard is `400`. |
| `resource` | `string` | yes | `srn:<project_id>:<resource_type>:<id>`, where the type is one the action's module registered, or for a built-in action one its module's routes check it on, and `<id>` may be `*` for an action on no single resource (a create or a list). A `projects:*` action is checked on the whole project, `srn:<project_id>:*:*`, which takes no `context.tags`. |
| `context` | `object` | no | What the conditions of a policy statement read. |

### `create-iam-token`

Issue an IAM token

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `policy` | `object` | no | An inline policy document, validated as `POST /api/v1/policies` validates one (`400 IAM_TOKEN_POLICY_INVALID` otherwise). Work the token starts holds this snapshot. |
| `policy_ids` | `array<string>` | no | Policies of the key's project or global ones, read as they stand at each request. An unknown id is `400 IAM_TOKEN_POLICY_INVALID`. |
| `principal` | `object` | no | A principal of the caller's own, opaque to the runtime. |
| `tool_context` | `object` | no | A `tool_context` layer the token pins: on every tool call the token makes, and every call its work starts (generations, nested `builtin` and `soat` calls, `call-tool` relays), a caller key the layer names is dropped in any casing and the layer's value is sent instead. Admission sees the caller's own bag. Keys follow the `tool_context` key grammar and may not be a server identity key (`INVALID_TOOL_CONTEXT_KEY`). A key under the deployment's reserved prefix (`SOAT_RESERVED_TOOL_CONTEXT_PREFIX`) needs `iam:PinReservedToolContext` on `srn:<project_id>:iam_token:*`, else `400 INVALID_TOOL_CONTEXT_KEY`. |
| `ttl_seconds` | `number` | no | Seconds until the token expires. |

### `revoke-iam-principal`

Revoke a principal

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | The project to revoke it in; defaults to the calling credential's project. |
| `principal` | `object` | yes | A principal of the caller's own, opaque to the runtime. |
