MCPLevelSequence User Guide

MCP Level Sequence is a self-contained Unreal Editor plugin that lets AI clients discover and edit Level Sequences through an MCP-compatible JSON-RPC 2.0 HTTP service. It supports Unreal Engine 5.2 and later without depending on other user plugins or cross-plugin shared modules.

1. Place Plugins/MCPLevelSequence in a project or engine plugin directory and enable it.
2. Start Unreal Editor. By default, the service starts at http://127.0.0.1:8762/mcp.
3. If the port is occupied, the server tries up to 10 following ports. Use the actual endpoint shown by the editor toolbar and log.
4. Configure the port, automatic startup, and request timeout under Project Settings > Plugins > MCP Level Sequence.

The service supports initialize, ping, tools/list, and tools/call. HTTP request bodies are limited to 1 MiB; larger requests receive HTTP 413. Requests must use jsonrpc: "2.0"; params and arguments must be objects, and each tool is checked against its schema for unknown fields, required fields, types, array items, and numeric bounds.

AddTrack supports eight track classes:

• Binding tracks: MovieScene3DTransformTrack, MovieSceneFloatTrack, MovieSceneBoolTrack, and MovieSceneSkeletalAnimationTrack.
• Root or binding tracks: MovieSceneAudioTrack and MovieSceneEventTrack.
• Root-only tracks: MovieSceneCameraCutTrack and MovieSceneFadeTrack.

Float and Bool property tracks require PropertyName and accept PropertyPath for nested properties. Skeletal Animation sections require AnimationAssetPath, validated as AnimSequenceBase; Audio sections require SoundAssetPath, validated as SoundBase. Event tracks currently create section containers only; they do not create Director Blueprint endpoints or event payloads.

Keyframe tools support three channel families: Double for Transform, Float for Float/Fade, and Bool for Bool property tracks. GetSequenceDetail returns track and section structure but does not enumerate channels; use the ChannelName contract for the selected track type when calling keyframe tools.

Every StartFrame, exclusive EndFrame, key position, and camera-cut frame uses the sequence’s TickResolution, not its DisplayRate. GetSequenceDetail returns both rational rates.

SetSequenceRates can set the Display Rate, Tick Resolution, or both. Each supplied rate requires a positive integer numerator and denominator. When Tick Resolution changes, the plugin uses the engine’s frame-time migration path for playback/selection ranges, tracks, sections, keys, and marked frames, preserving real time. It does not recursively modify Subsequence assets.

• ListSequences: 100 by default, capped at 500 per page.
• ListBindings: 100 by default, capped at 500 and stably sorted by BindingId.
• GetKeyframes: 200 by default, capped at 1000 and returns NextOffset.
• GetSequenceDetail: pages a stable combined Binding/Track/Section traversal with Offset and MaxItems.
• CaptureSequencerView: at most 16 Mi pixels and 8 MiB of compressed PNG data.

Paged responses report totals, the current offset, whether more data exists, and a NextOffset when applicable. Clients should continue paging instead of assuming that one response contains the whole asset.

Mutation and save tools accept only valid /Game/... Level Sequence paths. Read-only discovery, inspection, opening, capture, and closing may access other readable sequence locations. Editing tools reject PIE/save/GC busy states and read-only MovieScenes, and use editor transactions for Undo.

A successful edit only marks the package dirty; it never saves implicitly. SaveAsset saves only the specified Level Sequence package. After requesting a close, CloseAsset queries editors for the asset and its subobjects again; if an editor refuses to close, the tool reports failure instead of a false success.

Binding and track removal cascade through owned objects. Binding removal also removes local Camera Cut sections that reference the subtree in the same transaction. Destructive operations are rejected for invalid, locked, read-only, or unresolved non-local Camera Cut sequence references. Name selectors report ambiguity instead of choosing the first match. Prefer BindingId from ListBindings and TrackName from GetSequenceDetail.

This request sets a 24 fps display rate and migrates Tick Resolution to 24000 fps:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "SetSequenceRates",
    "arguments": {
      "AssetPath": "/Game/Cinematics/MySequence",
      "DisplayRateNumerator": 24,
      "DisplayRateDenominator": 1,
      "TickResolutionNumerator": 24000,
      "TickResolutionDenominator": 1
    }
  }
}

The recommended flow is to call ListSequences and GetSequenceDetail, perform mutations with stable IDs/names, and then call SaveAsset explicitly.

UE 5.8’s experimental Animation Assistant Toolset is a broad Python surface that depends on SequencerScripting. This plugin deliberately keeps a self-contained C++ HTTP boundary compatible with UE 5.2+. This pass adds the capabilities that have stable cross-version APIs: sequence rate editing, Skeletal Animation tracks/sections, and Audio asset sections.

The following differences are intentional:

• Subsequence creation/navigation needs cycle checks, hierarchy ownership, and cross-sequence time semantics, so write tools are not exposed yet.
• Spawnable creation has version-sensitive template ownership, Undo, and spawner paths and needs dedicated runtime validation before exposure.
• Event payloads depend on Director Blueprint endpoints/graphs. The current plugin creates Event sections but does not promise a concrete trigger.
• Arbitrary track/class creation, folders, tags, selection state, and advanced bone-level operations remain outside the reviewed strict-schema surface, although the official experimental toolset is broader.

Compilation, editor operation, asset save and close interactions, and complete Undo behavior have not yet been validated across UE 5.2 through 5.8. Check these operations in a copy of your project in the target engine first.

For questions or feedback, email mzsh.me@icloud.com. I will respond when I see your message.