Scenario MCP guide

The plugin runs a local Scenario MCP server inside the Unreal Editor. An agent connected to it (Claude Code, Codex, Cursor, Claude Desktop or any MCP client) can read your level, price and run Scenario models and workflows, then import and place the results, in the editor that is open on your machine.

1. Connect an agent

1. Open the Agent page in the Scenario Studio (toolbar menu: More > Agent, or the agent dot in the Studio header).
2. Check that the page says Scenario MCP on with its address (http://127.0.0.1:9877/mcp unless that port was taken). If the server is off, turn on its switch.
3. Under Connect a client, click Set up next to your agent (Reconnect once it is set up). The plugin writes the server and its token into the agent's configuration, after saving a timestamped backup of the file (<file>.scenario-backup-YYYYMMDD-HHMMSS). A file it cannot read is left untouched.
4. Restart the agent, or reload its MCP servers.
5. Optional: Install the agent skill copies the scenario-unreal skill to ~/.claude/skills/. It teaches Claude the tool order and the spending rules.

For any other client, Copy setup puts the URL, the header and ready-made snippets on the clipboard. A typical JSON entry:

{
  "mcpServers": {
    "scenario-unreal": {
      "type": "http",
      "url": "http://127.0.0.1:9877/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Never paste the token into a chat. New token... replaces it; connected agents then need Reconnect.

The editor must be open, signed in to Scenario, with a team and project chosen. Epic's own Unreal MCP server (port 8000 when enabled) is a different server. In Unreal 5.8 it also reaches Scenario, as a toolset (section 8). Both servers can be connected at once.

2. Permissions

Reading the level (summaries, object details, screenshots, assets, the output log) and checking prices are always allowed. Agents never see your Scenario credentials.

3. Spending

Every paid call follows the same contract as the Studio:

1. estimate_cost (or estimate_workflow, estimate_prompt) is free and returns a quote_id and cu_cost_exact.
2. generate (or run_workflow, approve_prompt) needs that quote_id and approved_cost equal to cu_cost_exact, character for character.
3. A quote is single use, bound to the exact model, settings and project, and expires after 120 seconds. Any change needs a new estimate.
4. A paid call is sent once. If the connection drops, the job becomes unknown and an identical request is blocked: call recover_local_job with action: "check", never generate again. Only you can mark a request as not sent.
5. With SCENARIO_NO_SPEND=1 in the editor's environment, every paid call is refused before anything is sent.

The plugin sets no Creative Unit cap of its own. The Activity list on the Agent page shows this session's agent calls, the latest 20, with the time, tool, client, the CU spent and any error.

4. Tools

Tool descriptions that spend start with SPENDS. Tools are annotated as read-only, destructive or idempotent for clients that use MCP annotations.

Status and level

Models and generation

Workflows, prompts, library and references

Landing results

Tool search (Editor Preferences > Plugins > Scenario > Agent tool search, off by default). The full tool list is about 29 KB, roughly 7,300 tokens, sent once per connection. With tool search on, tools/list holds four tools (about 1.4 KB): scenario_status, find_tools (names, kinds and descriptions matching a query), describe_tools (input schemas) and call_tool (runs a tool by name with the same permissions and money rules). Every tool also stays callable by its own name. Turn it on for a client that loads every tool into the model's context; clients that already defer tool definitions (Claude Code, for one) do not need it. It takes effect when the server restarts (the switch on the Agent page).

Kit: worlds, games and films (need the Change this project permission; distances in meters)

5. A session, step by step

Ask: "Put a mossy stone well next to the selected house."

1. scenario_status, then scene_summary to find the selection and the camera.
2. list_models { "lane": "3d" } and model_schema on the first pick.
3. estimate_cost { "model_id": "<pick>", "parameters": { "prompt": "mossy medieval stone well, <unreal_ready_prompt>" } } returns a quote_id and cu_cost_exact.
4. The agent tells you the price, then calls generate { "quote_id": "...", "approved_cost": "<cu_cost_exact>" }.
5. wait_for_job until delivered is true.
6. prepare_result_application with purpose: "place", placement: "at_location" and a point beside the house from object_detail.
7. apply_result_application. With changes off, you click Approve in the editor.
8. The agent reports the asset and actor it created and asks before save_changes.

6. Security

• The server listens on 127.0.0.1 only. It refuses requests whose Host is not a loopback name and any request from a web page (Origin header), so a website cannot drive it.
• The bearer token is random, stored in the system credential store, and compared in constant time. Turn Agent token off only for a client that cannot send headers.
• Tool results never contain Scenario credentials. Error messages have signed URLs and authorization headers removed.
• What an agent reads through the server (level summaries, screenshots, results) goes to that agent's model provider, under your agreement with that provider.

7. Troubleshooting agents

| A spend through Epic's Unreal MCP answers pending_approval although Approve each spend here is off | Expected: Epic's server has no token, so every paid call from it waits for you (section 8). |

8. Using Scenario through Epic's Unreal MCP

Unreal 5.8 ships an Experimental Model Context Protocol plugin: an MCP server inside the editor that exposes Epic's Toolset Registry through three tools, list_toolsets, describe_toolset and call_tool. On 5.8 the Scenario plugin registers a toolset there, so an agent connected to Epic's server can price and run Scenario models and land the results, next to Epic's own toolsets for actors, materials, Blueprints and the rest of the editor.

Turn it on

1. Unreal 5.8. The Scenario plugin enables Epic's Toolset Registry plugin (an optional dependency, with the plugins it needs: Python Editor Script Plugin, Editor Scripting Utilities and File Sandbox). On 5.6 and 5.7 there is no registry and nothing changes.
2. Enable Model Context Protocol in Edit > Plugins and start its server: its Auto Start Server setting (search for Model Context Protocol in the settings), or -ModelContextProtocolStartServer on the command line. It listens on port 8000 by default, path /mcp.
3. Connect your agent to that server with Epic's own setup. The Agent page shows, under Epic's Unreal MCP, whether that server is running and on which port.

What the agent sees

• Toolset ScenarioToolsets.ScenarioToolset, 19 tools: GetStatus, ListModels, GetModelSchema, RecommendModels, EstimateCost, Generate, ListWorkflows, GetWorkflowSchema, EstimateWorkflow, RunWorkflow, GetJobStatus, WaitForJob, ListJobs, CancelJob, CheckUnknownJob, SearchAssets, PrepareResult, ApplyResult, SaveChanges. They run the same actions as the tools of the same purpose on the Scenario MCP server.
• Agent skill /Script/ScenarioToolsets.ScenarioAgentSkill, listed by Epic's ToolsetRegistry.AgentSkillToolset (ListSkills, GetSkills). It carries the live state (signed in, project, Change this project, spending switch, lanes) and the rules the tool descriptions cannot: price first, never repeat a paid call, apply then save, and which work belongs to Epic's toolsets.
• Optional parameters have a word as default (all, auto, default, *, selection, none) because Epic's registry fills a left-out parameter only from its default. Parameters and Inputs are JSON object text, for example {"prompt": "a stone well"}.
• Not in the toolset: Python, removals, kit tools, uploads, Prompt Spark, and level reads and screenshots (Epic's toolsets cover the level).

A call through Epic's server:

{ "name": "call_tool", "arguments": {
  "toolset_name": "ScenarioToolsets.ScenarioToolset",
  "tool_name": "EstimateCost",
  "arguments": { "modelId": "<model id>", "parameters": "{\"prompt\": \"mossy stone well\"}" } } }

Spending. Epic's server has no token: any program on this computer can call it. So through the registry:

• Reads, prices (EstimateCost, EstimateWorkflow) and job status are free and need no approval.
• Generate and RunWorkflow check the quote and approved_cost first, then answer at once with state: "pending_approval" and an approval_id, and ask you in the editor, whatever Approve each spend here says. Approve sends the request once; Decline, or no answer before the quote expires, sends nothing. The agent follows the approval_id with GetJobStatus or WaitForJob; it becomes the job once sent.
• The quote rules are the same: single use, 120 seconds, bound to the exact request. Asking again with the same quote returns the same approval. A paid call is never retried. SCENARIO_NO_SPEND=1 refuses before you are asked.
• ApplyResult and SaveChanges follow Change this project, as on the Scenario MCP server.

Sizes. Epic's tools/list is three tools, about 1.7 KB. describe_toolset for the Scenario toolset is about 11.6 KB (about 2,900 tokens), loaded only when the agent asks for it.

More: Troubleshooting.