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

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 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. 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 (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) 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, this implementation uses PaginationRequest.FromParams to parse constraints like maxNodes and maxDepth before serializing the scene tree.

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

The response follows the standard contract:

{
  "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 (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).

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

The response returns integer IDs rather than full objects:

{
  "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 (lines 30-38). This resource converts the full asset database into a PaginationResponse<Dictionary<string,string>> (lines 140-155 in Pagination.cs), allowing efficient browsing of large folders.

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

The response includes GUID and path information:

{
  "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 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, FindGameObjects.cs, or 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}