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.
Connect your agent
Section titled “Connect your agent”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:
claude mcp add --transport http unreal-mcp http://127.0.0.1:8000/mcpOr add a .mcp.json file to the project folder:
{ "mcpServers": { "unreal-mcp": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } }}.cursor/mcp.json
{ "mcpServers": { "unreal-mcp": { "url": "http://127.0.0.1:8000/mcp" } }}.vscode/mcp.json
{ "servers": { "unreal-mcp": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } }}.gemini/settings.json
{ "mcpServers": { "unreal-mcp": { "httpUrl": "http://127.0.0.1:8000/mcp" } }}.codex/config.toml
[mcp_servers.unreal-mcp]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.
How the agent finds the tools
Section titled “How the agent finds the tools”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.Example prompts
Section titled “Example prompts”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.Tool reference
Section titled “Tool reference”Crowd placement
Section titled “Crowd placement”| Tool | What it does |
|---|---|
describe_crowds | Lists every VAS crowd in the open level with its components, meshes and instance counts. Agents start here |
list_animated_meshes | Lists vertex animated meshes in the level that are not part of a crowd |
list_brushes | Lists the crowd brushes in the project |
add_crowd | Adds instances at exact world locations using a brush |
fill_area | Fills a circle with crowd, with spacing, jitter and ground snapping |
fill_grid | Places crowd in rows and columns, for seating blocks, terraces and lines |
fill_arc | Places crowd in curved rows around a centre point, for round stands and bowls |
erase_crowd | Erases crowd inside a box, optionally only one brush’s instances |
transform_crowd | Moves, turns, scales or grounds the crowd inside a box |
duplicate_crowd | Copies the crowd inside a box and moves the copies by an offset |
Animation
Section titled “Animation”| Tool | What it does |
|---|---|
check_crowd_health | Finds instances that render but will not animate |
list_animations | Lists the animations each component can play |
play_animation | Plays an animation on instances, all of them or inside an area, with random start offsets |
set_playback | Changes play rate, pause, position, reverse or controlled time |
step_animation | Steps instances forward or back by frames |
get_instance_state | Reports one instance’s animation mode, animation, StateTree and playback |
assign_state_tree | Assigns a StateTree to instances |
trigger_event | Sends a gameplay tag animation event, with optional delay, wave and per-frame spreading |
list_animation_lists | Lists the animation lists on each component |
create_animation_list | Adds an animation list to each component |
remove_animation_list | Removes an animation list from a component |
play_animation_list | Plays an animation list on instances |
set_custom_data | Sets a per-instance custom data value, optionally on a fraction of instances |
get_custom_data | Reads a custom data value from instances |
clear_custom_data | Removes values set with set_custom_data |
randomise_custom_data | Rerolls the random per-instance custom data |
Assets
Section titled “Assets”| Tool | What it does |
|---|---|
list_asset_collections | Lists the VAS asset collections in the project |
describe_asset_collection | Shows a collection’s type, meshes, animations and whether it is built |
create_asset_collection | Bakes skeletal meshes and animations into an asset collection (bone or vertex) |
rebuild_asset_collection | Adds or removes animations, then rebuilds and saves |
export_asset_collection | Exports a built collection as Unreal assets or files, for use without the plugin |
create_brush | Creates a crowd brush for an asset collection, optionally with a StateTree |
delete_asset | Deletes an asset collection, crowd brush or VAS StateTree |
list_state_trees | Lists the StateTrees that use the VAS schema |
describe_state_tree | Reads a VAS StateTree into the same format build_state_tree takes |
build_state_tree | Builds, compiles and saves a complete VAS StateTree from a description |
Building StateTrees
Section titled “Building StateTrees”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
eventare taken when that gameplay tag event reaches the instance. Without aneventthey 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.
Things to know
Section titled “Things to know”- 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.