Skip to content

MCP tools and command catalog

An agent connected to Studio over MCP sees a list of tools. Tool names start with studio_. This page lists them, then explains the command catalog, which reaches every Studio operation that has no named tool.

Studio has far too many commands for one tool each: that would fill an agent’s context before it read a single description, so the common operations have named tools and everything else goes through the catalog.

Every tool is either a read tool or a write tool. An organization’s MCP credential allows both. A tool that changes the model says so in its description, and the descriptions of destructive tools tell the agent to use them only when a person asked.

Every tool that takes an identifier checks that it is a real identifier, and when it is not, tells the agent to read the structure or the model first instead of inventing one. When a tool creates something, it makes the new identifier itself and reports it back.

Tool What it does
studio_whoami Says which organization the agent is connected to
studio_get_structure Reads the projects, applications, domains and boards the agent can reach
studio_locate Turns names into the identifiers other tools need
studio_list_event_models Lists the event models
studio_get_event_model Reads one event model
studio_list_brainstorming_boards Lists the brainstorming boards
studio_get_brainstorming_board Reads what is on a brainstorming board
studio_get_board_findings Returns what the event model board shows as findings: compiler errors and the gaps in the model, such as read model fields no event fills, command properties no event captures, events nothing consumes and slices without specifications

Event models are described in Screenplay. Studio forwards edits to the Screenplay tools instead of carrying its own copy of every edit, so an outside agent gets the same read, propose, validate and apply steps that Studio’s own agents get.

Tool What it does
studio_create_event_model Creates a new event model
studio_screenplay_open Exports an event model into a scratch workspace and returns a session and the Screenplay tools
studio_screenplay_call Runs one Screenplay tool in the session: read the syntax, look at the model, propose typed edits, apply an accepted proposal to the workspace
studio_screenplay_apply Turns what changed in the workspace into Studio’s own changes, so it shows on the board and in its history, and reports what was done and what could not be applied
studio_screenplay_close Abandons a session

A session is tied to the one event model it was opened on and to the organization that opened it. A session that is not used for thirty minutes is closed, and an organization can hold five open at a time.

The workspace holds the board’s screens, with their navigation, toolbar slice buttons and template references, and the sample data chosen for the application. Applying changes saves changed screens and adds new sample data packs. Some changes cannot be applied: edits to an existing sample data pack, removal of a pack or its selection, and removal of a screen from a slice. Studio reports these as not translated instead of applying them.

Concepts do not travel through this path yet. Use the concept tools below.

Tool What it does
studio_create_brainstorming_board Creates a board
studio_add_brainstorming_event, studio_rename_brainstorming_event, studio_move_brainstorming_event, studio_remove_brainstorming_event Work with events
studio_add_brainstorming_sticky_note, studio_update_brainstorming_sticky_note, studio_update_brainstorming_sticky_note_colour, studio_move_brainstorming_sticky_note, studio_remove_brainstorming_sticky_note Work with sticky notes
studio_add_brainstorming_region, studio_rename_brainstorming_region, studio_move_brainstorming_region, studio_remove_brainstorming_region Group the board in regions
studio_add_brainstorming_event_to_region, studio_add_brainstorming_sticky_note_to_region Place items in a region
studio_add_brainstorming_chat, studio_add_brainstorming_chat_to_region, studio_send_brainstorming_chat_message Add a chat, place it, and send a message, optionally as a persona of the domain
studio_arrange_brainstorming_board Lays the board out as a column per region with the items in a grid. Arranging twice gives the same board

A sticky note’s color carries its meaning: yellow for a question, pink for a risk, green for a decision and blue for an assumption. Orange and purple are free.

Concepts, constraints, state machines and workflows

Section titled “Concepts, constraints, state machines and workflows”
Tool What it does
studio_list_concepts, studio_add_concept, studio_update_concept Work with the domain’s concepts
studio_list_constraints, studio_add_constraint, studio_add_event_to_constraint, studio_configure_constraint_event, studio_remove_event_from_constraint Work with constraints
studio_list_state_machines, studio_add_state_machine, studio_add_state_machine_state, studio_add_state_machine_transition Work with state machines
studio_list_workflows, studio_add_workflow, studio_add_workflow_node, studio_connect_workflow_nodes Work with workflows

The constraints canvas, the personas canvas, the event sources board, the given contexts board and the seed data board each have the same six tools for their sticky notes. Replace <canvas> with constraint, persona, event_source, given_context or seed_data:

studio_list_<canvas>_sticky_notes, studio_add_<canvas>_sticky_note, studio_update_<canvas>_sticky_note, studio_update_<canvas>_sticky_note_colour, studio_move_<canvas>_sticky_note and studio_remove_<canvas>_sticky_note.

Every one of these takes the identifiers of the board it works on.

Tool What it does
studio_export_context Exports a slice, a feature, an event model or a domain with its specifications, its Screenplay and the Screenplay guidance. See Agent context

Five tools let a coding agent on your machine take part in a board’s chat. They are described in Live modeling: studio_connect_local_agent, studio_poll_local_agent, studio_take_local_agent_prompt, studio_answer_local_agent_prompt and studio_disconnect_local_agent.

Use the catalog when an operation has no named tool. It lets an agent discover Studio’s commands and queries, read their arguments and call them in your organization.

Tool What it does
studio_list_areas Lists the areas the catalog is grouped in
studio_find_commands, studio_find_queries Searches commands or queries by what they do
studio_describe_command, studio_describe_query Reads a command’s or query’s arguments
studio_execute_command Runs a command with a payload built from its description
studio_perform_query Runs a query

The workflow is always the same. Find the command, describe it, then execute it with the payload the description shows. The agent should not guess a payload from the command’s name. Use the queries afterward to read the resulting state. Take identifiers from the structure and model tools, never from memory.

For example, to define how a concept’s values are generated, find DefineConceptGeneration, read its arguments, then execute it.

A concept names a domain value, such as an order identifier. Give a concept a generation strategy when Studio should describe how to create the value, as with order references or invite codes. Do not use one for facts a person supplies, such as a name.

A concept can keep one of these strategies: uuid, uuidv7, ulid, typeid, nanoid or bytes, together with its prefix, letter case, size, alphabet, byte count and encoding where they apply. Screenplay decides which options fit each strategy and primitive when you export.

The concepts canvas has no generation controls yet, so use the command catalog:

  • DefineConceptGeneration takes the concept’s identifier and a strategy, with settings that fit the strategy. bytes needs both a byte count and an encoding (base64url, hex or base32). A size must be from 1 to 256 and a byte count from 1 to 512. Other settings you leave out use the strategy’s defaults.
  • RemoveConceptGeneration clears the strategy without deleting the concept.

Both refuse a concept that does not exist. Studio also refuses to define generated values on a concept marked as personal data.

Export writes the strategy as a Screenplay generate clause, and import keeps the six strategies and their options. A plain uuid strategy on a Uuid concept needs no clause, because it is already the default. Import warns before it drops pattern, random or rule strategies, and warns when a concept already exists and is left unchanged.

Rules on a generated concept are checked against the strategy when you export. Each rule comes back as one of:

  • Proven. Every value the strategy can make satisfies the rule.
  • Refuted. The strategy can make a value that breaks the rule. Export refuses that rule and names the strategy and a value that breaks it. The rest of the model still exports, and the concept is left out until you change the rule or the strategy.
  • Unproven. Screenplay could not decide, for example for an ambiguous pattern. Export succeeds and warns, naming the concept, the rule and the reason.

Two queries give the same answers without exporting. AllConceptGenerationStrategies lists the strategies Screenplay publishes, with their primitives, options and ranges. ConceptAssessmentsForDomain returns, for each generated concept in a domain, its findings, the proof status of each rule and the entropy of the strategy.

When a concept’s personal-data protection changes after an event revision was released, rendering and generation refuse the affected slices and ask for a new event generation. The refusal names the event, the concept and the release it was admitted in. Studio reads the release baseline from the connected repository’s default branch to know what was released; this is release evidence, not a report from a live Chronicle. If the repository or the baseline cannot be read, Studio keeps a warning instead of refusing.

After you configure a strategy or change protection, preview a slice that uses the concept to see the planned output and any diagnostics before you generate.