Cómo Construimos un Servidor MCP en Tiempo Real para Godot

Por Qué el “Tiempo Real” Importa para un Servidor MCP en Godot

La mayoría de las demostraciones de MCP funcionan con un mundo tipo REST: el modelo hace una pregunta, una herramienta devuelve JSON, y a nadie le importa si el viaje de ida y vuelta tomó dos segundos. Godot es diferente. El editor posee un árbol de escenas vivo, importaciones de recursos y un bucle de modo de juego. Si tu servidor MCP bloquea el hilo principal—o solo ve una copia estática del proyecto—los clientes de IA dejan de sentirse como copilotos y empiezan a sentirse como editores de archivos remotos con pasos adicionales.

Cuando diseñamos Godot MCP para VberAI, el encargo fue explícito:

• Un asistente de IA (Cursor, Claude, Windsurf y clientes MCP similares) debe operar el editor, no solo leer archivos .gd del disco
• Acciones como crear nodo, renombrar, adjuntar script y consultar selección deben completarse mientras el editor sigue respondiendo
• Los contextos de modo de juego y modo de edición deben mantenerse honestos—las herramientas deben fallar de forma clara cuando una operación no es segura durante el juego

Esta publicación es la historia de ingeniería: cómo construimos un servidor MCP en tiempo real que se sitúa junto a Godot en lugar de fingir que el proyecto es un repositorio estático.

El Problema con el MCP “Solo Archivos” para Motores

Un enfoque ingenuo es tentador:

1. Apuntar el servidor MCP a la carpeta del proyecto
2. Exponer read_file / write_file / list_dir
3. Dejar que el modelo invente GDScript y esperar que el editor recargue bien

Eso funciona para sitios de documentación. Falla para el trabajo de motores porque:

• La propiedad de las escenas vive en memoria — los diffs .tscn sin guardar, las escenas abiertas y la selección del editor son invisibles en el disco
• Los pipelines de importación tienen estado — escribir un PNG no es lo mismo que “recurso listo con ajustes de importación correctos”
• Las señales y las rutas de nodo son datos de grafo — las ediciones de cadenas rompen el cableado silenciosamente
• La latencia se acumula — cada confirmación de “¿apareció el nodo?” se convierte en otro escaneo completo del sistema de archivos

Necesitábamos una superficie MCP que refleje lo que un humano ya ve en el dock de Godot: jerarquía, propiedades con forma de inspector y manejadores de recursos—no solo cadenas de ruta.

Resumen de la Arquitectura

A alto nivel, Godot MCP son tres capas que cooperan:

Cliente MCP (Cursor / Claude / …)
        │  JSON-RPC sobre stdio o transporte local
        ▼
Servidor MCP (proceso puente de VberAI Godot)
        │  cola de comandos + sobres de resultados
        ▼
Plugin del Editor de Godot (GDExtension / plugin de editor)
        │  llamadas diferidas en el hilo principal
        ▼
Árbol de Escenas del Editor / ResourceDB / Editor de Scripts

Capa 1 — Superficie de herramientas MCP

Las herramientas son intencionalmente pequeñas y con forma de verbo:

• godot_get_scene_tree — instantánea de la escena editada con tipos de nodo y rutas
• godot_create_node / godot_set_property
• godot_attach_script / godot_run_script_snippet (protegido)
• godot_list_resources / godot_get_selection

Evitamos una herramienta gigante de do_anything. Las herramientas más pequeñas son más fáciles de validar, más fáciles de registrar y más difíciles de abusar por un modelo para hacer parches sin límites.

Capa 2 — el puente en tiempo real

El puente es donde realmente vive el “tiempo real”:

• Un canal bidireccional entre el proceso MCP y el plugin del editor (socket local o tubería con nombre en desarrollo; las compilaciones de producto pueden envolverlo detrás del asistente de escritorio de VberAI)
• Una cola de comandos que serializa las mutaciones para que dos llamadas de herramientas superpuestas no compitan por el árbol de escenas
• IDs de solicitud + acuses de recibo para que el cliente MCP pueda esperar a que se “aplique” sin sondear el sistema de archivos
• Heartbeat / actividad del editor para que los clientes sepan cuándo Godot se cerró a mitad de sesión

Capa 3 — seguridad del hilo principal en Godot

Las APIs de UI y escenas de Godot no son de hilos libres. El plugin nunca muta nodos en el hilo de E/S de MCP. En su lugar:

1. El comando MCP llega al hilo del puente
2. La carga útil se pone en cola
3. El callback diferido del editor se ejecuta en el hilo principal (call_deferred / enganche de frame inactivo)
4. El sobre de resultados devuelve éxito, error estructurado o “reintentar después de que termine el modo de juego”

Ese patrón es aburrido a propósito. Lo aburrido es lo que evita que el “tiempo real” se convierta en “congelaciones aleatorias del editor”.

Haciendo que se Sienta en Tiempo Real (Sin Mentir sobre la Latencia)

“Tiempo real” aquí no significa latencia cero mágica. Significa que el bucle de retroalimentación coincide con cómo trabajan los humanos en el editor.

Instantánea vs flujo

Los primeros prototipos devolvían todo el árbol de escenas en cada llamada. Eso colapsaba en configuraciones grandes de mundo abierto. Cambiamos a:

• Instantáneas superficiales por defecto (raíz + un nivel, o enfocadas en la selección)
• Lecturas con ámbito de ruta cuando el modelo ya conoce un subárbol
• Tokens de cambio opcionales para que las llamadas posteriores puedan preguntar “¿qué cambió desde X?” en lugar de re-serializar todo

Resultados amigables para diffs

Los resultados de las herramientas incluyen:

• Cadenas canónicas de NodePath
• Nombres de tipo (CharacterBody2D, Control, …)
• Claves de propiedades que se asignan limpiamente a los campos del inspector
• Advertencias explícitas cuando se aplicó una escritura pero la escena sigue sucia / sin guardar

Los modelos iteran más rápido cuando los resultados se ven como estado de UI, no como una publicación de blog de texto libre.

Comportamiento acotado en modo de juego

El modo de juego es donde comienza la mitad de los tickets de “la IA rompió mi proyecto”. Nuestro conjunto de reglas:

Modo	Permitido	Bloqueado o con compuerta
Edición	Mutaciones de escena, consultas de recursos	Eliminaciones destructivas de proyecto sin confirmación
Juego	Mayormente lectura / consulta de nodos en ejecución	Ediciones estructurales a la escena editada
Transición	Esperar / sugerencias de reintento	No-ops silenciosos

Errores claros superan a la astucia. Si el modelo no puede editar durante el juego, la respuesta MCP lo dice en forma estructurada—para que el cliente pueda decirle al usuario que detenga el juego y luego reintente.

Problemas Difíciles que Enfrentamos (y Mantuvimos)

1. El editor no es una base de datos

El orden de los nodos, las relaciones de propiedad y las escenas empaquetadas interactúan de maneras que se ven simples en un GIF y desordenadas en un .tscn. Nos apoyamos en las propias APIs de Godot (Node, EditorInterface, cargadores de recursos) en lugar de inventar un modelo de escena paralelo que se desviaría.

2. Scripts vs escenas como dos fuentes de verdad

Adjuntar un script no es lo mismo que asegurar que el script compila y que el nombre de la clase se resuelve. El servidor informa los resultados de compilación/adjuntado por separado. Eso detuvo una clase de fallos de “la herramienta dijo éxito, el Inspector no muestra nada”.

3. Sesiones multi-ventana / multi-proyecto

Los desarrolladores abren más de una instancia de Godot. El puente se vincula a un ID de sesión de editor explícito para que las llamadas de herramientas no caigan en el proyecto equivocado después de un fin de semana de suspensión + reapertura.

4. Límites de seguridad

Un servidor MCP que puede reescribir escenas es poderoso. Transporte local primero, listas de permitidos de herramientas explícitas y sin exfiltración silenciosa a la nube del árbol completo del proyecto son innegociables. “Asistente de IA” y “shell remoto sobre tu juego” deben seguir siendo categorías de producto distintas.

Cómo Encaja Junto a AI Studio y el Resto de VberAI

Godot MCP es el operador del motor. Piezas complementarias:

• VberAI Studio (AI Studio) — estructura de diseño a motor para Figma/PSD → jerarquías de Control; MCP luego conecta botones y renombra nodos después de la importación
• Unity MCP / Cocos MCP — la misma idea MCP, diferentes anfitriones de editor y reglas de seguridad
• AI Super Matting — limpia el alfa antes de que las texturas se conviertan en recursos del motor que MCP asigna más tarde

La tesis compartida: la IA debe tocar la superficie de producción viva (editor, activos, escenas), no solo el repositorio como texto.

Consejos Prácticos si Estás Construyendo tu Propio MCP de Motor

1. Pon en cola las mutaciones en el hilo principal del motor — nunca pretendas que los motores de juego son servidores sin estado compartido
2. Prefiere herramientas pequeñas con esquemas — la validación supera a la poesía de prompts
3. Devuelve NodePaths y tipos, no prosa — los modelos necesitan manejadores operables
4. Codifica los modos de juego/edición en cada respuesta — la ambigüedad aquí destruye la confianza
5. Mide el viaje de ida y vuelta hasta “visible en el dock” — no solo el tiempo de codificación JSON

Si solo optimizas el proceso MCP e ignoras el puente del editor, enviarás un bucle rápido de alucinaciones.

Conclusión

Construir un servidor MCP en tiempo real para Godot significó tratar al editor como un colaborador vivo: un puente en cola y seguro para el hilo principal; herramientas con forma de acciones de editor; y honestidad sobre los límites del modo de juego. El MCP solo de archivos es más fácil—e incompleto para el trabajo nativo de escenas.

¿Quieres el camino ya enviado en lugar de un prototipo de fin de semana? Comienza con VberAI Godot MCP, conecta tu cliente MCP preferido y prueba una primera llamada de herramienta trivial: lista el árbol de escenas actual, luego crea un nodo bajo la selección. Ese único bucle—consultar → mutar → verlo en el dock—es el producto. Todo lo demás es ingeniería de confiabilidad a su alrededor.