Custom Tools Development

Custom Tools Development

One of the most powerful features of Unity-MCP is the ability to extend it with your own tools. You can expose your own game logic, utility functions, or editor scripts to the AI.

The [McpPluginTool] Attribute

To create a tool, simply add the [McpPluginTool] attribute to any C# method in your project. It works with static methods or instance methods (if the class is registered, but static is easiest for utilities).

Basic Example

using com.IvanMurzak.McpPlugin.Common; // Attributes namespace
using UnityEngine;
using System.ComponentModel; // For Description attribute

// 1. Mark the class
[McpPluginToolType]
public class MyGameTools
{
    // 2. Mark the method
    [McpPluginTool("spawn-enemy", Title = "Spawn Enemy")]
    [Description("Spawns an enemy of a specific type at a position.")]
    public static string SpawnEnemy(
        [Description("The type of enemy (e.g., 'Orc', 'Goblin')")] string type,
        [Description("X,Y,Z position")] Vector3 position
    )
    {
        // 3. Run on Main Thread if touching Unity API
        return MainThread.Instance.Run(() =>
        {
            var prefab = Resources.Load<GameObject>($"Enemies/{type}");
            if (!prefab) return $"Error: Enemy type '{type}' not found.";

            var instance = Object.Instantiate(prefab, position, Quaternion.identity);
            return $"Success: Spawned {instance.name} at {position}";
        });
    }
}

How It Works

1. Discovery: When the Unity Plugin starts (or recompiles), it scans for [McpPluginToolType] classes.
2. Registration: Valid methods are registered as MCP Tools.
3. Usage: The AI Client will instantly see spawn-enemy in its tool list.
4. Execution: When the AI uses the tool, your method is called.

Return Values

The method should return a string (or Task<string>). The returned string is the "output" the AI reads.

• Return "Success: ..." or JSON data for success.
• Return "Error: ..." if something went wrong.

Parameters

Supported parameter types:

• int, float, bool, string
• Vector2, Vector3, Quaternion
• Color
• Enum types

Use [Description] on parameters to help the AI understand what to pass.