# MCP tools

Tools wrap shared v1 logic (not HTTP loopback). Unless noted, `workspaceId` defaults to the API key's workspace.

| Tool | Scope | Maps to |
|------|-------|---------|
| `list_workspaces` | `workspaces:read` | `GET /workspaces` |
| `list_buckets` | `buckets:read` | `GET .../buckets` |
| `list_files` | `files:read` | list + optional search/semantic |
| `get_file` | `files:read` | `GET .../files/{fileId}` |
| `search_files` | `files:read` | keyword + semantic |
| `similar_files` | `files:read` | similar neighbors |
| `ask_agent` | `agent:run` | bucket agent |
| `update_file` | `files:write` | tags / description |
| `get_intelligence` | `intelligence:read` | config + progress |
| `start_backfill` | `intelligence:write` | start / resume / pause |
| `presign_download` | `files:download` | download URL |
| `presign_upload` | `files:upload` | upload URL |
| `create_folder` | `files:write` | mkdir |

## Common args

Most bucket tools take:

- `bucketId` (required)
- `workspaceId` (optional; defaults to key workspace)

### `list_files` / `search_files`

- `prefix?`, `parentPrefix?`, `search?`, `tag?`
- `semantic?` (boolean)
- `limit?`, `offset?`

### `ask_agent`

- `query` (string)

### `update_file`

- `fileId`, `tags?`, `description?`

### `start_backfill`

- `action`: `start` | `pause`
- `estimateToken?` (required for `start`)

### `presign_upload`

- `key`, `contentType?`

### `presign_download`

- `key?` or `fileId?`

### `create_folder`

- `key` (folder path)

## Resources

Doc markdown is exposed as MCP resources (`file.rocks://docs/...` and/or https `.md` URIs) so clients can pull API/MCP docs as context.

## Errors

Missing scope or bucket allowlist → tool error with a clear message (same semantics as REST 403).