StageDesigner

AI assistant through MCP

Connect Claude, Claude Code or Codex to your StageDesigner account. The assistant reads projects and builds stages, lighting, cabling or sound systems, and every change goes into the version history.

8 min read
Documentation contents ▾
Add a 12 × 4 m stage with railingsand arc seating for about 400 people.Saved version 15:• stage 12 × 4 m, h 1.0 m, railings• seating 412 seats, 1.2 m aisleedit_scene · add_stageClaude · Codex · other MCP appsevery change is a new project versionthat you can restore
A conversation with the AI assistant adding a stage and audience seating to the project.

MCP (Model Context Protocol) is a standard that lets AI apps use the tools of other programs. StageDesigner provides an MCP server with tools for reading and editing the projects in your company cloud. Once connected, you write to the assistant in plain language, and it calls the tools: creates a project, draws the venue, adds a stage built from platforms, audience seating, screens, trusses with fixtures, a control room, a sound system and a cabling plan.

Server address

The address is the same for all accounts: https://api.stagedesigner.pl/mcp. You can copy it in the app with the Copy server address button.

DockProjectAI integration

The AI integration panel (in the dock with the description "MCP server for Claude and Codex") shows the connection status, connected apps, connection instructions with an App switch (Claude, Claude Code, Codex), recent AI activity and the personal token. The panel requires signing in. The assistant works on the projects of the company selected in the Team panel.

Connecting: Claude (claude.ai and the app)

  1. In the StageDesigner app, open AI integration and click Copy server address.
  2. In Claude, open Settings → Connectors → Add custom connector.
  3. Paste the server address and click Connect.
  4. A StageDesigner page opens asking for consent. Sign in if needed, choose the company and access scope, and click Allow.
  5. You return to Claude. The StageDesigner connector is ready to use in conversations.

Connecting: Claude Code

  1. In the terminal, paste the command from the panel (Add server command field): claude mcp add --transport http stagedesigner https://api.stagedesigner.pl/mcp.
  2. Start Claude Code and type /mcp.
  3. Choose the stagedesigner server → Authenticate.
  4. In the browser, approve access on the StageDesigner consent page.

Connecting: Codex

  1. In the terminal, paste the first command: codex mcp add stagedesigner --url https://api.stagedesigner.pl/mcp.
  2. Paste the second command: codex mcp login stagedesigner.
  3. In the browser, approve access on the StageDesigner consent page.

The consent page asks: "Connect "<app>" to your account?" and shows where you will return after consenting. If the app is not recognized, you will see a warning: allow only if you are the one adding it in your AI tool.

Company
A dropdown, if you belong to several companies. A connection applies to one company. For a second company, add a separate connection.
Full editing
Creating and changing projects, uploading 3D models and images for screens.
Read-only
Browsing projects and scene descriptions, no changes.

With the Viewer role in the selected company, the full editing option is disabled. Regardless of scope, the assistant sees only the projects you have access to and changes only those you can edit (Project access).

What the assistant can do

  • Create projects (empty with a room, outdoor or technical view environment, or from a ready arrangement) and duplicate them as options.
  • Build the venue layout plan: a room with walls, doors and windows, a stage built from platforms with stairs and railings, backstage, bars, lounge zones, banquet tables, audience seating in rows, an arc or wings, clear zones and evacuation routes.
  • Add LED screens and walls, furniture and equipment, fixtures, solids, 3D models from a web address, and images or video for screens.
  • Design truss structures with statics, hang fixtures, loudspeakers and screens on them, apply lighting presets.
  • Create a control room, propose and insert a sound system, calculate acoustics.
  • Plan cabling: power, phases, DMX, network, LED data, video and audio, and fix warnings.
  • Read the report, the spatial description of the scene and module data, save and restore versions, return the preview link.

You will find the full list of tools in AI assistant tools, and ready prompts in Example prompts.

Changes live and in the history

Every saving call is atomic: all operations in a batch run together or none do. A successful save creates one version in the project history. If you have the project open, the scene reloads by itself, and a message shows the app name and a description of the change. If you have unsent changes at that moment, the app asks which version to keep (Newer version in the cloud window).

The Recent activity section in the AI integration panel groups AI saves by project. Each entry has a success or error icon, a description, the time and the version number. How to undo an AI change is described in Version history with the team and AI.

Connected apps and disconnecting

After consent, the panel shows the Connected status and the Connected apps section. Each item has a name, scope (Edit or Read) and time of last use. The Connected indicator also shows next to the panel entry in the dock.

  1. In the Connected apps section, click Disconnect next to the app.
  2. Confirm: "Disconnect "…"? The app will lose access to projects."
  3. The AI app loses access right away. To connect it again, go through the consent page once more.

Personal token

A personal token is for tools that cannot sign in through a browser, e.g. scripts or servers. It gives access to your company projects in the chosen scope.

  1. In the AI integration panel, expand the Personal token section.
  2. Enter a Name (by default the name of the selected app), so you can recognize the token in the list.
  3. Choose the Scope: Edit or Read.
  4. Click Create token.
  5. Copy the token right away. For security reasons the app will not show it again.
  6. Click Done.

Below the token, the panel shows a command for Codex that reads the token from an environment variable: codex mcp add stagedesigner --url https://api.stagedesigner.pl/mcp --bearer-token-env-var STAGEDESIGNER_TOKEN. Before running it, set the STAGEDESIGNER_TOKEN variable to the copied token. Other tools pass the token in the Authorization: Bearer <token> header.

How to write prompts

  • Start with a brief: type of event, number of guests, venue or outdoor, dimensions, stage, screens, lighting mood. The assistant asks only about what it really needs.
  • Give numbers in meters and specific values: "stage 12 × 6 m, height 1 m", "screen 10 × 5.6 m, pitch 2.9 mm".
  • Refer to the project by name ("in the 25th Anniversary Gala project…"). The assistant finds it in the project list.
  • Build in stages: venue and stage first, then the technical side. After each stage, review the result in the app.
  • Ask for checks: "check the warnings and fix them". The assistant has tools for automatic fixes in structures, cabling, control room and acoustics.
  • Before a big change, ask for a version save with a label.
  • Say it plainly when you want something deleted. By default the assistant adds to your work rather than deleting it, and a deleted project goes to the trash for 30 days.

Limitations

  • Up to 600 operations in one scene editing call and up to 200 in a technical module call, about 15 seconds of calculation per batch, up to 12,000 objects in the scene. The assistant splits large projects into several calls.
  • The assistant does not drag objects with handles and does not save PDFs. It returns the report as text, data or printable HTML, the control room diagram as text, and the acoustics map as a simplified character map.
  • The assistant sees live sources (NDI, Syphon, screen capture) in the list only when you have the app open on your account, and they play only on the computer that receives them.
  • The assistant downloads 3D models and images from public https addresses or from data sent in the conversation. Addresses on private networks are blocked.
  • At most 16 enabled lights with real shading are recommended to keep the scene smooth.
Did not find the answer?
Describe the problem and we will reply with a solution or add an article.