How to Customize Unity MCP Features: A Complete Guide to Tool Groups and Extensions

You customize Unity MCP features by toggling tool groups through the manage_tools meta-tool or by extending the system with custom Python server tools and C# Unity handlers registered under new group tags.

Unity MCP (Model Context Protocol) bridges AI assistants and the Unity Editor through a bidirectional architecture. The CoplayDev/unity-mcp repository splits functionality between Python server tools that expose RPC endpoints and C# editor tools that execute Unity operations. Learning how to customize Unity MCP features lets you tailor AI capabilities to specific workflows—whether you need VFX, animation, UI, or entirely bespoke internal tools.

Architecture of Unity MCP Feature Toggling

The system uses a tool group abstraction to organize related capabilities. When an AI assistant sends a request, the Python server evaluates visibility rules to determine which tools are advertised to the client.

Server-Side Tool Registration

In Server/src/services/tools/manage_tools.py, tools register via the @mcp_for_unity_tool decorator (lines 53-119). This decorator stores metadata—including the group tag—in the tool registry. Groups use the format group:<name> (e.g., group:vfx, group:animation), and the server filters requests based on these tags.

Unity Editor Tool Attributes

On the Unity side, C# tools in MCPForUnity/Editor/Tools/ carry matching group tags via the [McpForUnityTool] attribute. For example, ManageScene.cs implements the server-side manage_scene tool and shares the same group metadata. This tight coupling allows the server to discover new capabilities automatically when you update the Unity package.

Customizing Features via the Meta-Tool

The manage_tools meta-tool acts as the control plane for feature visibility. It accepts JSON-RPC commands to modify which tool groups are active in the current session.

Controlling Tool Group Visibility

Send these commands from any MCP client (Claude, Cursor, or CLI) via STDIO, HTTP, or WebSocket transports:

• list_groups – Returns all groups with descriptions, current enabled state, and contained tool names
• activate – Enables a group by adding a visibility rule (e.g., {"action":"activate","group":"vfx"})
• deactivate – Disables a group (e.g., {"action":"deactivate","group":"ui"})
• sync – Queries the Unity editor for current GUI toggle states and updates server visibility rules (lines 83-99)
• reset – Clears session-specific rules and falls back to DEFAULT_ENABLED_GROUPS (lines 111-118)

Extending Unity MCP with Custom Tools

You can add entirely new capabilities by creating paired implementations in both the Python server and the Unity editor.

Creating a Python Server Tool

Add a new file under Server/src/services/tools/ and register it with the decorator:

# Server/src/services/tools/my_custom_tool.py

from fastmcp import Context
from services.registry import mcp_for_unity_tool, ToolAnnotations

@mcp_for_unity_tool(
    description="My custom operation on Unity objects.",
    group="myfeatures",               # new group name

    annotations=ToolAnnotations(title="My Custom Tool")
)
async def my_custom_tool(ctx: Context, name: str) -> dict:
    from services.tools.utils import send_with_unity_instance
    params = {"name": name}
    return await send_with_unity_instance(
        async_send_command_with_retry, 
        await get_unity_instance_from_context(ctx),
        "my_custom_tool", 
        params
    )

Implementing the C# Unity Handler

Add the corresponding handler in the Unity package:

// MCPForUnity/Editor/Tools/MyCustomTool.cs
[McpForUnityTool("my_custom_tool", Group = "myfeatures")]
public static class MyCustomTool
{
    public static object HandleCommand(JObject @params)
    {
        var p = new ToolParams(@params);
        string name = p.RequireString("name");
        // Perform Unity API calls here
        return new SuccessResponse($"Created object {name}");
    }
}

Registering New Tool Groups

Add your new group to TOOL_GROUPS in the server registry, and optionally include it in DEFAULT_ENABLED_GROUPS. The manage_tools meta-tool will immediately list the new group in its output, allowing runtime activation without server restarts.

Runtime Configuration in the Unity Editor

Using the GUI Tool Panel

Open Window → MCP for Unity → Configure Tools to access group toggles. Each tool group appears with a checkbox that writes state directly to the Unity-side configuration.

Synchronizing States

Press Sync in the UI or call manage_tools with action="sync" to propagate Unity GUI changes to the Python server. This ensures the server’s visibility rules match your editor preferences before AI assistants begin issuing commands.

Summary

• Use the meta-tool to toggle feature groups at runtime via manage_tools actions like activate, deactivate, and reset

• Extend functionality by creating paired Python/C# tools using @mcp_for_unity_tool and [McpForUnityTool] attributes with matching group tags

• Synchronize states between the Unity Editor and Python server using the sync action to ensure visibility rules align

• Register new groups in TOOL_GROUPS and DEFAULT_ENABLED_GROUPS to make custom tools discoverable without modifying server core code

Frequently Asked Questions

How do I temporarily disable specific Unity MCP features?

Send a manage_tools command with {"action":"deactivate","group":"ui"} (substituting ui with your target group). This adds a visibility rule that hides the group's tools from the AI client until you reactivate them or reset the session.

Which files must I edit to add a custom tool to Unity MCP?

Create a Python file in Server/src/services/tools/ for the server-side RPC handler, and a C# file in MCPForUnity/Editor/Tools/ for the Unity Editor implementation. Both must share the same tool name and group tag to function as a pair.

How does Unity MCP synchronize tool states between the editor and server?

The sync action in Server/src/services/tools/manage_tools.py (lines 83-99) queries the Unity Editor for the current toggle state of each tool group and updates the server's visibility rules accordingly, ensuring the AI client only sees enabled capabilities.

Can I create new tool groups beyond the default ones like vfx and ui?

Yes. Define new group names in the group parameter of your @mcp_for_unity_tool decorator and [McpForUnityTool] attribute, then add the group to TOOL_GROUPS in the server registry. The manage_tools meta-tool automatically discovers and lists custom groups alongside built-in ones.

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