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.
Read access and write access
Section titled “Read access and write access”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.
Start here: read and navigate
Section titled “Start here: read and navigate”| 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 in Screenplay
Section titled “Event models in Screenplay”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.
Brainstorming boards
Section titled “Brainstorming boards”| 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 |
Sticky notes on the other canvases
Section titled “Sticky notes on the other canvases”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.
Context for a coding agent
Section titled “Context for a coding agent”| 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 |
Live modeling
Section titled “Live modeling”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.
The command catalog
Section titled “The command catalog”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.
Generated values
Section titled “Generated values”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:
DefineConceptGenerationtakes the concept’s identifier and a strategy, with settings that fit the strategy.bytesneeds both a byte count and an encoding (base64url,hexorbase32). 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.RemoveConceptGenerationclears 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.
How export treats generated values
Section titled “How export treats generated values”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.
Personal data on events already released
Section titled “Personal data on events already released”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.