# Shares MCP Tools

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

# Shares

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

### `create-share`

Create a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | The publishing project (required if not using project key auth) |
| `resource` | `string` | yes | The SRN of one resource in the publishing project, `srn:<project_id>:<type>:<id>`. No wildcard. |
| `actions` | `array<string>` | yes | The actions granted: `tools:CallTool` for a `tool`, `agents:CreateAgentGeneration` for an `agent`. Any other action is `400 VALIDATION_FAILED`. |
| `grantee` | `string` | yes | The project the share is offered to, or `*` for every project. Never the publishing project itself. |
| `cap` | `any \| null` | no | The calls each accepting project may make through the share per fixed window; a call past it is `429 SHARE_CAP_EXCEEDED`. Omit or `null` for no cap. |

### `list-shares`

List shares

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID (required if not using project key auth, and always for `role=grantee`) |
| `role` | `string` | no | Which side of the shares to list |
| `resource` | `string` | no | Only shares of this resource SRN (`role=publisher` only) |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `get-share`

Get a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `project_id` | `string` | no | The project the caller reads as. Omit, or name the publisher, for the publisher's view; name a grantee project for its view. |

### `update-share`

Update a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `cap` | `any \| null` | no | The calls each accepting project may make through the share per fixed window; a call past it is `429 SHARE_CAP_EXCEEDED`. `null` removes the cap. |

### `delete-share`

Delete a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |

### `accept-share`

Accept a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `project_id` | `string` | no | The accepting project (required if not using project key auth) |

### `suspend-share`

Suspend a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |

### `resume-share`

Resume a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |

### `revoke-share`

Revoke a share

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `force` | `boolean` | no | As a grantee, revoke even while the project's resources name the shared resource; they degrade as for a revoked share. |
| `project_id` | `string` | no | The project the caller revokes for. Omit, or name the publisher, to revoke the share; name a grantee project to revoke its acceptance. |

### `list-share-references`

List a grantee's references to a shared resource

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `project_id` | `string` | no | The grantee project whose references to list. |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `list-share-acceptances`

List a share's acceptances

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `status` | `array<string>` | no | Only acceptances in these statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`. |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `revoke-share-acceptance`

Revoke an acceptance

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `acceptance_id` | `string` | yes | Share acceptance ID |

### `delete-share-acceptance`

Delete an acceptance

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `share_id` | `string` | yes | Share ID |
| `acceptance_id` | `string` | yes | Share acceptance ID |