# Enabling and Using Tool Groups in Unity MCP (VFX, Animation, UI, Testing)

> Easily activate Unity MCP tool groups like VFX, Animation, UI, and Testing using the manage tools function. Streamline your workflow and boost productivity today.

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

---

**Activate specific Unity MCP tool groups like VFX, Animation, UI, and Testing by calling the `manage_tools` function with `action='activate'` and the desired group name.**

Unity MCP (Multiplayer Command Protocol) organizes its server-side capabilities into modular **tool groups** that remain disabled by default to keep the AI assistant's context focused. This article explains how to enable and utilize these specialized groups—including **VFX**, **Animation**, **UI**, and **Testing**—within the [CoplayDev/unity-mcp](https://github.com/CoplayDev/unity-mcp) repository.

## How Unity MCP Tool Groups Work

Unity MCP implements a permission system where each tool is tagged with a `group` parameter in its `@mcp_for_unity_tool` decorator. While the `"core"` group is automatically active, specialized domains require explicit activation. The server maintains an in-memory registry tracking which groups are currently exposed.

When a group is deactivated, its associated tools are hidden from the AI assistant entirely. Activation makes them callable for the duration of the server process.

## Core Implementation Files

### The manage_tools Meta-Tool

The [[`Server/src/services/tools/manage_tools.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/manage_tools.py)](https://github.com/CoplayDev/unity-mcp/blob/beta/Server/src/services/tools/manage_tools.py) file contains the primary interface for toggling group visibility:

```python
async def manage_tools(
    ctx: Context,
    action: Literal["activate", "deactivate"],
    group: str,
) -> dict:
    ...

```

- **action**: Accepts `"activate"` to expose tools or `"deactivate"` to hide them.
- **group**: The string identifier matching the tool category (e.g., `"vfx"`, `"testing"`).

### Specialized Tool Registrations

Each domain-specific tool declares its group membership via decorators in the following files:

- **VFX**: [[`Server/src/services/tools/manage_vfx.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/manage_vfx.py)](https://github.com/CoplayDev/unity-mcp/blob/beta/Server/src/services/tools/manage_vfx.py) registers with `group="vfx"`
- **Animation**: [[`Server/src/services/tools/manage_animation.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/manage_animation.py)](https://github.com/CoplayDev/unity-mcp/blob/beta/Server/src/services/tools/manage_animation.py) registers with `group="animation"`
- **UI**: [[`Server/src/services/tools/manage_ui.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/manage_ui.py)](https://github.com/CoplayDev/unity-mcp/blob/beta/Server/src/services/tools/manage_ui.py) registers with `group="ui"`
- **Testing**: [[`Server/src/services/tools/run_tests.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/run_tests.py)](https://github.com/CoplayDev/unity-mcp/blob/beta/Server/src/services/tools/run_tests.py) registers with `group="testing"`

### Group Documentation Resource

The [[`Server/src/services/resources/tool_groups.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/resources/tool_groups.py)](https://github.com/CoplayDev/unity-mcp/blob/beta/Server/src/services/resources/tool_groups.py) file exposes metadata describing available groups and activation syntax:

```python
{
    "usage": "Call manage_tools(action='activate', group='<name>') to enable a group."
}

```

## Enabling Tool Groups Step by Step

To activate **Unity MCP tool groups** for your session:

1. Obtain the MCP context object provided by the server runtime.
2. Invoke `manage_tools` with `action="activate"` and the target group string.
3. Verify activation by attempting to call a tool from that group.

```python

# Activate the VFX group

await manage_tools(
    ctx=context,
    action="activate",
    group="vfx"
)

# Activate additional groups as needed

await manage_tools(ctx=context, action="activate", group="animation")
await manage_tools(ctx=context, action="activate", group="ui")
await manage_tools(ctx=context, action="activate", group="testing")

```

## Working with Specific Tool Groups

### VFX Tools

Once you activate the `"vfx"` group via `manage_tools`, you gain access to particle system and VFX Graph manipulation functions. These tools in [`manage_vfx.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_vfx.py) allow automated creation of visual effects, modification of particle parameters, and asset instantiation.

### Animation Tools

The `"animation"` group exposes controller and state machine management via [`manage_animation.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_animation.py). After activation, you can programmatically create Animator controllers, set animation parameters, and trigger state transitions through MCP calls.

### UI Tools

Activating the `"ui"` group unlocks canvas and component operations from [`manage_ui.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_ui.py). This enables automated layout generation, RectTransform adjustments, and UI element instantiation without manual editor interaction.

### Testing Tools

The `"testing"` group connects to Unity's Test Runner framework through [`run_tests.py`](https://github.com/CoplayDev/unity-mcp/blob/main/run_tests.py). Once enabled, you can execute PlayMode and EditMode test suites remotely and retrieve results.

```python

# Example: Run automated tests

await manage_tools(ctx, action="activate", group="testing")
result = await run_tests(ctx, test_suite="PlayMode", timeout_seconds=300)

```

## Practical Implementation Examples

The following patterns demonstrate **enabling tool groups in Unity MCP** for real-world workflows:

**VFX Asset Creation:**

```python
await manage_tools(ctx, action="activate", group="vfx")
await manage_vfx(
    ctx, 
    action="create", 
    name="PortalEffect", 
    preset="SciFiPortal"
)

```

**UI Layout Generation:**

```python
await manage_tools(ctx, action="activate", group="ui")
await manage_ui(ctx, action="create_canvas", name="HUDCanvas")
await manage_ui(
    ctx, 
    action="add_text", 
    parent="HUDCanvas", 
    content="Score: 0"
)

```

**Automated Test Execution:**

```python
await manage_tools(ctx, action="activate", group="testing")
test_results = await run_tests(
    ctx, 
    test_suite="All", 
    timeout_seconds=600
)

```

## Summary

- **Unity MCP tool groups** partition functionality into VFX, Animation, UI, and Testing domains to control context window size.
- The `manage_tools` function in [`Server/src/services/tools/manage_tools.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/manage_tools.py) serves as the exclusive mechanism for group activation.
- Only the `core` group is active by default; all others require `manage_tools(action='activate', group='<name>')`.
- Group activation persists for the server process lifetime but resets on server restart.
- Domain tools reside in [`manage_vfx.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_vfx.py), [`manage_animation.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_animation.py), [`manage_ui.py`](https://github.com/CoplayDev/unity-mcp/blob/main/manage_ui.py), and [`run_tests.py`](https://github.com/CoplayDev/unity-mcp/blob/main/run_tests.py).

## Frequently Asked Questions

### How do I verify which tool groups are currently active?

The Unity MCP server maintains an internal registry of active groups within the `manage_tools` implementation. While there is no direct query function exposed in the base files, attempting to call a tool from an inactive group returns a specific error, allowing you to infer group state. Check the server logs for activation confirmations when `manage_tools` executes successfully.

### Can I activate multiple groups in a single call?

No, the current `manage_tools` signature in [`Server/src/services/tools/manage_tools.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/manage_tools.py) accepts only one `group` parameter per invocation. To enable multiple domains, chain separate `manage_tools` calls for each group (e.g., `"vfx"`, then `"animation"`, then `"ui"`).

### What error occurs if I call a tool without activating its group?

The MCP server returns a "Tool not available" or "Group not active" error. Because tools are filtered based on their declared `group` decorator parameter, calling `manage_vfx` or `run_tests` before activating their respective groups results in the tool being hidden from the AI assistant entirely.

### Do tool group settings persist after restarting Unity?

No, activation states are stored in-memory within the Python MCP server process. When Unity or the MCP server restarts, all groups except `"core"` revert to inactive. Implement a startup initialization script that calls `manage_tools` for required groups at the beginning of each session.