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

> Customize Unity MCP features by toggling tool groups via manage_tools or extending with custom Python server tools and C# Unity handlers. Master MCP customization.

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

---

**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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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:

```python

# 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:

```csharp
// 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`](https://github.com/CoplayDev/unity-mcp/blob/main/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.