Herramientas personalizadas

Puedes añadir tus propias herramientas MCP a Godot MCP en C# puro, dentro de tu proyecto. Una herramienta personalizada es un método que el agente de IA puede llamar, con una descripción que indica al modelo qué hace. Esta página cubre las herramientas de editor, la regla del hilo principal y el runtime opcional que permite a un agente comunicarse con un juego en ejecución.

Escribe una herramienta de editor#

Una familia de herramientas es una partial class marcada con [AiToolType]. Cada herramienta es un método marcado con [AiTool("tool-name")], con un [Description] en el método y en cada parámetro para que el modelo sepa cuándo y cómo llamarla.

using System.ComponentModel;
using com.IvanMurzak.McpPlugin;           // [AiToolType], [AiTool]
using com.IvanMurzak.ReflectorNet.Utils;  // MainThread

[AiToolType]
public partial class Tool_MyFeature
{
    [AiTool("my-custom-task", Title = "Do a custom task")]
    [Description("Explain to the LLM what this does and when to call it.")]
    public string CustomTask
    (
        [Description("Explain to the LLM what this parameter is.")]
        string inputData
    )
    {
        // Work that does not touch the Godot API can run here, on a background thread.

        return MainThread.Instance.Run(() =>
        {
            // Touch EditorInterface, Node or Resource here, on the main thread.
            return "[Success] Operation completed.";
        });
    }
}

Compila el proyecto de C# (el botón Build del editor, godot-cli build, o pide al agente que ejecute script-build). Godot recarga el ensamblado, el complemento se reconecta y la nueva herramienta aparece en la lista de herramientas del agente y en la ventana Tools del dock.

Reglas que mantienen fiables las herramientas#

• Solo el hilo principal para los objetos de Godot. Los métodos de las herramientas se llaman fuera del hilo principal. Cualquier llamada a Node, Resource, SceneTree o EditorInterface debe pasar por MainThread.Instance.Run(...). Tocarlos desde el hilo en segundo plano puede hacer que el editor se bloquee.
• Devuelve datos, no texto formateado. Devuelve una clase con propiedades (se serializa para el modelo), o void para herramientas que solo producen efectos secundarios. Evita las cadenas construidas a mano para cualquier cosa que el agente necesite analizar.
• Marca los parámetros opcionales. Usa un tipo que admita null con un valor predeterminado, por ejemplo string? filter = null, y el modelo tratará el parámetro como opcional.
• Descríbelo todo. Las descripciones son lo que lee el modelo. Di qué hace la herramienta, cuándo usarla y qué significa cada parámetro.
• El código exclusivo del editor va detrás de #if TOOLS. El código que usa API del editor no debe compilarse en un juego exportado.

Indicaciones y destinos#

[AiTool] acepta indicaciones opcionales como ReadOnlyHint = true e IdempotentHint = true, que indican a los clientes que la herramienta no cambia nada o que se puede repetir sin riesgo. Un Target decide dónde se registra una herramienta: ToolTarget.Editor (solo editor), ToolTarget.Runtime (solo juego) o el valor predeterminado, ambos.

Deja que el agente escriba la herramienta#

La herramienta de sistema godot-skill-create escribe un nuevo archivo de herramienta en C# en tu proyecto; la herramienta se podrá llamar tras la siguiente compilación. Antes de escribir una nueva herramienta, comprueba si RQL ya cubre la tarea: casi todo el acceso a datos del editor (nodos, recursos, archivos, ajustes del proyecto) está a un rql-query o rql-mutate de distancia. Consulta Herramientas.

Herramientas en un juego en ejecución#

Godot MCP también puede ejecutarse dentro de un juego en ejecución o exportado, en debug o release. Esto permite que un agente lea y controle el estado del juego en vivo, por ejemplo un juego de ajedrez cuyos movimientos del bot provienen de un LLM. Hay dos cosas deliberadas:

• Nunca se conecta por sí solo. Tu código decide si y cuándo llamar a Connect().
• No expone nada de forma predeterminada. Tú registras cada herramienta, prompt y recurso. Las herramientas de editor del complemento no se compilan en la compilación de un juego.

Inícialo una vez que exista un SceneTree, por ejemplo desde el _Ready() de un autoload:

using System.Reflection;
using com.IvanMurzak.Godot.MCP.Connection;
using com.IvanMurzak.Godot.MCP.Runtime;
using McpServerConsts = com.IvanMurzak.McpPlugin.Common.Consts.MCP.Server;
using Godot;

public partial class GameMcp : Node
{
    private GodotMcpRuntimeHandle? _mcp;

    public override async void _Ready()
    {
        _mcp = GodotMcpRuntime.Initialize(builder =>
        {
            builder.WithConfig(config =>
            {
                config.ConnectionMode = GodotMcpConnectionMode.Custom;
                config.Host = "http://localhost:8080";
                config.AuthOption = McpServerConsts.AuthOption.token;
                config.Token = "your-secret-token";
            });
            builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly());
        }).Build();

        await _mcp.Connect();
    }

    public override async void _ExitTree()
    {
        if (_mcp is not null)
            await _mcp.Disconnect();
    }
}

Marca las clases de herramientas exclusivas del juego con [AiToolType(Target = ToolTarget.Runtime)] (de com.IvanMurzak.McpPlugin.Common), para que el editor no las registre y el agente llegue al juego incluso mientras el editor está conectado.

Opciones del builder#

El host y el token también pueden venir de variables de entorno GODOT_MCP_* o de un archivo .env, que tienen prioridad sobre el código. Un juego nunca lee los ajustes guardados del editor.

Prompts y recursos#

Además de las herramientas, un juego puede exponer prompts de MCP (plantillas de instrucciones con nombre, [AiPromptType] con métodos [AiPrompt]) y recursos (contenido de solo lectura obtenido por URI, [AiResourceType] con métodos [AiResource]). Cada tipo es opcional y se registra de la misma forma que las herramientas.

Ejecutar C# dentro del juego#

Para permitir que el agente ejecute C# en el juego, actívalo en el archivo .csproj del juego y llama a WithScriptExecute():

<PropertyGroup>
  <GodotMcpCodeExecInGame>true</GodotMcpCodeExecInGame>
  <DefineConstants>$(DefineConstants);GODOT_MCP_CODE_EXEC_IN_GAME</DefineConstants>
</PropertyGroup>

Esto solo funciona en compilaciones de escritorio con CoreCLR, no en NativeAOT ni en iOS.

Lista de comprobación de seguridad para compilaciones de juegos#

• Prefiere el modo Custom en localhost o 127.0.0.1 con AuthOption.token y un token real.
• Registra solo las herramientas que necesites; la superficie de ataque es exactamente las herramientas que registres.
• No expongas la conexión en una interfaz de red pública en una compilación de lanzamiento a menos que la hayas diseñado y protegido para ello.

Para ver la lista completa de herramientas, consulta Herramientas; para los conjuntos de herramientas empaquetados, consulta Extensiones.