# How to Use Paging with MCP manage_scene, manage_gameobject, and manage_asset in Unity

> Learn to implement paging with Unity MCP's manage_scene, manage_gameobject, and manage_asset tools. Safely handle large datasets using cursor-based pagination for efficient data management.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: how-to-guide
- Published: 2026-07-06

---

**The CoplayDev/unity-mcp repository implements a standardized cursor-based pagination system across `manage_scene`, `manage_gameobject`, and `manage_asset` tools, using `PaginationRequest.FromParams` for input parsing and `PaginationResponse<T>.Create` for output generation to safely handle large Unity datasets.**

MCP (Model Context Protocol) tools expose Unity Editor functionality to AI assistants. When querying large collections like scene hierarchies, GameObject sets, or asset libraries, the unity-mcp framework prevents context window overload by implementing a consistent pagination contract in [`MCPForUnity/Editor/Helpers/Pagination.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Helpers/Pagination.cs) that all listing tools share.

## The Pagination Contract in unity-mcp

The pagination system follows a strict request-response pattern defined in [`MCPForUnity/Editor/Helpers/Pagination.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Helpers/Pagination.cs). This ensures uniform behavior whether you are traversing scene hierarchies, searching GameObjects, or listing assets.

### Request Parameters

All paginated tools accept these optional parameters via `PaginationRequest.FromParams`:

- **`pageSize`** – Number of items to return (default: 50)
- **`cursor`** – Starting position for the current page (default: 0)
- **`maxNodes`** – Maximum total nodes to traverse (tool-specific)
- **`maxDepth`** – Maximum hierarchy depth (scene hierarchy only)
- **`maxChildrenPerNode`** – Child limit per parent node (scene hierarchy only)

In [`MCPForUnity/Editor/Tools/ManageScene.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Tools/ManageScene.cs) (lines 48-55), the `get_hierarchy` action extracts these parameters to control tree traversal depth and breadth.

### Response Structure

The `PaginationResponse<T>.Create` method (lines 112-130 in [`Pagination.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/Pagination.cs)) generates a standardized payload containing:

- **`items`** – The array of results for the current page
- **`next_cursor`** – Integer offset for the next page, or `null` if exhausted
- **`has_more`** – Boolean indicating if additional pages exist
- **`total_count`** – Total available items (when calculable)

## Paginating Scene Hierarchy with manage_scene

The `manage_scene` tool supports pagination specifically in the `get_hierarchy` action. Located in [`MCPForUnity/Editor/Tools/ManageScene.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Tools/ManageScene.cs), this implementation uses `PaginationRequest.FromParams` to parse constraints like `maxNodes` and `maxDepth` before serializing the scene tree.

```json
{
  "tool": "manage_scene",
  "action": "get_hierarchy",
  "pageSize": 20,
  "cursor": 0,
  "maxDepth": 3,
  "includeTransform": true
}

```

The response follows the standard contract:

```json
{
  "status": "success",
  "data": {
    "items": [
      { "id": 101, "name": "Main Camera", "transform": {...} },
      { "id": 102, "name": "Directional Light", "transform": {...} }
    ],
    "next_cursor": 20,
    "has_more": true,
    "total_count": 124
  }
}

```

To retrieve subsequent pages, increment the `cursor` to match the `next_cursor` value from the previous response until `has_more` returns `false`.

## Paginating GameObject Searches with manage_gameobject

For GameObject queries, the `find_gameobjects` action in [`MCPForUnity/Editor/Tools/FindGameObjects.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Tools/FindGameObjects.cs) (lines 48-55) leverages the same pagination helper. After collecting all matching object IDs based on filters like `nameContains` or component types, the tool returns a paginated slice using `PaginationResponse<int>.Create` (lines 117-135 in [`Pagination.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/Pagination.cs)).

```json
{
  "tool": "manage_gameobject",
  "action": "find_gameobjects",
  "nameContains": "Enemy",
  "pageSize": 10,
  "cursor": 0
}

```

The response returns integer IDs rather than full objects:

```json
{
  "status": "success",
  "data": {
    "items": [3021, 3025, 3030, 3045],
    "next_cursor": 10,
    "has_more": true,
    "total_count": 27
  }
}

```

These IDs can be passed to other MCP tools like `inspect_gameobject` for detailed property inspection without loading the entire search result set into the context window.

## Paginating Asset Lists with manage_asset

Asset enumeration uses the `list_assets` action implemented in [`MCPForUnity/Editor/Resources/Asset/AssetListResource.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Resources/Asset/AssetListResource.cs) (lines 30-38). This resource converts the full asset database into a `PaginationResponse<Dictionary<string,string>>` (lines 140-155 in [`Pagination.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/Pagination.cs)), allowing efficient browsing of large folders.

```json
{
  "tool": "manage_asset",
  "action": "list_assets",
  "folder": "Assets/Textures",
  "pageSize": 50,
  "cursor": 0
}

```

The response includes GUID and path information:

```json
{
  "status": "success",
  "data": {
    "items": [
      { "guid": "a1b2c3d4e5f6...", "path": "Assets/Textures/grass.png" },
      { "guid": "b2c3d4e5f6g7...", "path": "Assets/Textures/wood.jpg" }
    ],
    "next_cursor": 50,
    "has_more": true,
    "total_count": 183
  }
}

```

As with other tools, continue advancing the cursor until `has_more` becomes `false` to enumerate the complete asset collection.

## Summary

- **Unified Contract**: All three tools (`manage_scene`, `manage_gameobject`, `manage_asset`) use `PaginationRequest.FromParams` and `PaginationResponse<T>.Create` from [`MCPForUnity/Editor/Helpers/Pagination.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Helpers/Pagination.cs) for consistent paging behavior.
- **Cursor-Based**: The system uses integer cursors (starting at 0) rather than page numbers, with `next_cursor` providing the offset for subsequent requests.
- **Default Limits**: `pageSize` defaults to 50 items per request, with additional tool-specific limits like `maxNodes` and `maxDepth` available for hierarchy queries.
- **Exhaustion Signal**: Each response includes `has_more` and `next_cursor`; when `has_more` is `false`, the cursor will be `null` and pagination is complete.

## Frequently Asked Questions

### What is the default page size if I don't specify one?

If you omit the `pageSize` parameter, the system defaults to 50 items per page as implemented in `PaginationRequest.FromParams`. You can override this by providing any positive integer value in your request JSON.

### How do I know when I have retrieved all items?

Check the `has_more` field in the response data. When `has_more` returns `false`, you have reached the final page. Additionally, `next_cursor` will be `null` rather than an integer when no further pages exist, providing a clear termination signal for your pagination loop.

### Can I use different page sizes for different tools in the same session?

Yes, each paginated request is independent. You can request 20 items from `manage_scene` in one call and 100 items from `manage_asset` in the next. The `pageSize` parameter is evaluated per-request in each tool's handler ([`ManageScene.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/ManageScene.cs), [`FindGameObjects.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/FindGameObjects.cs), or [`AssetListResource.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/AssetListResource.cs)).

### Does the cursor support random access or only sequential traversal?

The cursor system uses integer offsets (0, 20, 40, etc.) calculated from the `pageSize` and current position. While you can theoretically jump to any cursor value, the intended usage is sequential traversal using the `next_cursor` value provided in the previous response to ensure consistency.