Unity MCP Tools

Expert knowledge for coordinating Unity MCP operations, including tool enablement, agent orchestration, and direct MCP tool usage.

Quick Start: MCP Workflow

1. Inspect First (Always Available)

CRITICAL: The MCP Resource is ALWAYS enabled and never disabled - no tool enablement needed. This is the primary way agents inspect Unity.

How to Access (works for all agents including subagents):

Tool: ReadMcpResourceTool
Server: ai-game-developer
URI: unity://gameobject/{scene}/{path}

Example:

{
  "server": "ai-game-developer",
  "uri": "unity://gameobject/GameplayScene/TileManager"
}

Returns: Transform, components, properties, children

Resource vs Tools Decision Table:

Most agents should use this resource for read operations before enabling any tools.

2. Enable Tools When Modification Needed

Run /unity-mcp-enable [groups] before instructing agents that need MCP to fulfill a task.

3. Spawn Agent with Skills

Include unity-mcp-tools skill for agents doing MCP work:

4. Cleanup After MCP Work

Run /unity-mcp-reset to disable tools and save context.

Commands Reference

Subagents cannot use these commands, but claude code can trigger them or ask the user to use them.

When to Consult mcp-advisor

Spawn the mcp-advisor advisory agent when:

• Unsure which tool groups are needed
• MCP tools returning errors
• Complex multi-step Unity operations
• Need troubleshooting help

Example prompt: "What MCP tool groups do I need to add a health bar UI?"

The mcp-advisor returns recommendations - it does not execute commands.

Agent Skill Assignments

When spawning agents, include these skills:

Subagent MCP Access

Subagents can use MCP tools directly when:

1. Tools are enabled in AI-Game-Developer-Config.json
2. Agent inherits tools (omit tools: field in frontmatter)

To give MCP access, omit the tools field:

---
name: scene-builder
skills: unity-mcp-tools, layout-sizing
# No tools field = inherits ALL including MCP
---

Subagent Constraints

If MCP tools aren't working: Report to orchestrator which tool groups you need enabled (e.g., "Need gameobject and component groups").

Tool Groups Reference

Use /unity-mcp-enable [group] to enable. Multiple: /unity-mcp-enable gameobject component

Core Groups and Tools (11 total)

Cross-cutting Utilities (Auto-included)

Common Patterns

Create GameObject with Components

1. Enable: /unity-mcp-enable gameobject component
2. Use gameobject-create to create object
3. Use gameobject-component-add to add components
4. Use gameobject-component-modify to configure

Run Tests After Code Changes

1. Enable: /unity-mcp-enable testing
2. Use tests-run with testMode: "EditMode" or "PlayMode"
3. Check results, fix failures

Inspect Before Modifying

Always use MCP Resource first (no enablement):

• /unity-mcp-scene-info {path} to understand structure
• Then enable tools only if modification needed

Configuration

Config file: Assets/Resources/AI-Game-Developer-Config.json

Structure:

{
  "tools": [{ "name": "tool-name", "enabled": true/false }],
  "resources": [{ "name": "GameObject from Current Scene by Path", "enabled": true }]
}

The MCP Resource is always enabled. Tools default to disabled.

Reference Files

This skill's references/ folder contains complete MCP documentation organized for efficient navigation.

Main Guides (4 files)

Tool Parameter Reference (11 files in tool-parameters/)

Detailed parameters and examples for each tool category:

Related Documentation

• Documentation/Unity-MCP-Documentation.md - Full MCP setup guide
• .mcp.json - Connection configuration
• Assets/Resources/AI-Game-Developer-Config.json - Tool enablement config