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

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 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/beta/Server/src/services/tools/manage_tools.py) file contains the primary interface for toggling group visibility:

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/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/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/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/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/beta/Server/src/services/resources/tool_groups.py) file exposes metadata describing available groups and activation syntax:

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

# 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 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. 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. 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. Once enabled, you can execute PlayMode and EditMode test suites remotely and retrieve results.

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

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

UI Layout Generation:

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:

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 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, manage_animation.py, manage_ui.py, and 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 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.

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