Skip to content

Using VAS with AI Agents

Once the MCP server is running, any agent that supports MCP over HTTP can connect to it and use the VAS toolsets. The editor must stay open while the agent works.

All of these point at the default address http://127.0.0.1:8000/mcp. Change it if you set a different port or path. Put project files in your Unreal project folder, next to the .uproject.

Run this from your project folder:

Terminal window
claude mcp add --transport http unreal-mcp http://127.0.0.1:8000/mcp

Or add a .mcp.json file to the project folder:

{
"mcpServers": {
"unreal-mcp": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp"
}
}
}

Restart the agent after adding the server. If it cannot connect, check the server is running and that nothing else is using port 8000.

By default Unreal MCP only shows the agent three tools: list_toolsets, describe_toolset and call_tool. The agent lists the toolsets, reads the ones it needs and calls tools through call_tool. This keeps the agent’s context small with many toolsets loaded.

If you would rather every tool appear directly in the agent, untick Enable Tool Search under Editor Preferences > Model Context Protocol.

You do not need to name tools in your prompts. Describe what you want and the agent picks the tools. A good first prompt is:

Describe the VAS crowds in the open level.
Fill the north stand with fans using BR_SoccerFans. Rows 100 units apart, seats 60 apart, all facing the pitch.
Make a StateTree for VA_SoccerFanFemale. Idle by default, cheer on VertexAnimation.Soccer.Cheer, then go back to idle. Assign it to the whole crowd.
Send a cheer to the crowd as a wave starting from the west end.
Set custom data 12 to 1 on a random 30% of the crowd.
Bake SK_Fan with every animation in /Game/Fans/Anims into a bone animation asset collection, then make a brush for it.
Check the stadium crowd for instances that won't animate.
ToolWhat it does
describe_crowdsLists every VAS crowd in the open level with its components, meshes and instance counts. Agents start here
list_animated_meshesLists vertex animated meshes in the level that are not part of a crowd
list_brushesLists the crowd brushes in the project
add_crowdAdds instances at exact world locations using a brush
fill_areaFills a circle with crowd, with spacing, jitter and ground snapping
fill_gridPlaces crowd in rows and columns, for seating blocks, terraces and lines
fill_arcPlaces crowd in curved rows around a centre point, for round stands and bowls
erase_crowdErases crowd inside a box, optionally only one brush’s instances
transform_crowdMoves, turns, scales or grounds the crowd inside a box
duplicate_crowdCopies the crowd inside a box and moves the copies by an offset
ToolWhat it does
check_crowd_healthFinds instances that render but will not animate
list_animationsLists the animations each component can play
play_animationPlays an animation on instances, all of them or inside an area, with random start offsets
set_playbackChanges play rate, pause, position, reverse or controlled time
step_animationSteps instances forward or back by frames
get_instance_stateReports one instance’s animation mode, animation, StateTree and playback
assign_state_treeAssigns a StateTree to instances
trigger_eventSends a gameplay tag animation event, with optional delay, wave and per-frame spreading
list_animation_listsLists the animation lists on each component
create_animation_listAdds an animation list to each component
remove_animation_listRemoves an animation list from a component
play_animation_listPlays an animation list on instances
set_custom_dataSets a per-instance custom data value, optionally on a fraction of instances
get_custom_dataReads a custom data value from instances
clear_custom_dataRemoves values set with set_custom_data
randomise_custom_dataRerolls the random per-instance custom data
ToolWhat it does
list_asset_collectionsLists the VAS asset collections in the project
describe_asset_collectionShows a collection’s type, meshes, animations and whether it is built
create_asset_collectionBakes skeletal meshes and animations into an asset collection (bone or vertex)
rebuild_asset_collectionAdds or removes animations, then rebuilds and saves
export_asset_collectionExports a built collection as Unreal assets or files, for use without the plugin
create_brushCreates a crowd brush for an asset collection, optionally with a StateTree
delete_assetDeletes an asset collection, crowd brush or VAS StateTree
list_state_treesLists the StateTrees that use the VAS schema
describe_state_treeReads a VAS StateTree into the same format build_state_tree takes
build_state_treeBuilds, compiles and saves a complete VAS StateTree from a description

build_state_tree takes a JSON description of the root state. The agent writes this for you, but it helps to know what it can describe:

{
"name": "Root",
"transitions": [{ "event": "VertexAnimation.Soccer.Cheer", "to": "Celebrate" }],
"children": [
{ "name": "Idle", "animations": ["A_Idle", "A_Idle_Breathing"], "loop": true },
{ "name": "Celebrate", "animations": ["A_Gesture_Victory"], "transitions": [{ "to": "Idle" }] }
]
}
  • animations plays a random pick from the list. Names must exist in the asset collection.
  • loop loops the animation. A state that does not loop completes when its animation ends.
  • play_rate sets playback speed. The default is 1.
  • transitions with an event are taken when that gameplay tag event reaches the instance. Without an event they are taken when the state completes.
  • A parent state runs its first child. Transitions on a parent apply to all of its children.

The finished tree is a normal VAS StateTree. You can open it and keep editing it by hand. See State Trees Overview for how the trees work.

  • The tools work on the level open in the editor, not in Play In Editor.
  • Custom data indexes 0 to 11 are reserved by VAS. Use 12 to 75 for your own values. See Per-Instance Custom Data.
  • Event tags must already exist in your project’s gameplay tag list. The VertexAnimation.Soccer.* demo tags ship with the plugin.
  • Asset paths start with /Game/, for example /Game/Crowd/ST_Fans.