Perch does not ship an AI. Instead it ships an MCP server, the Perch MCP server, that plugs Perch’s knowledge into the assistant you already use on your own account: the display vocabulary and the Luau definition file, these docs, the builtin packages as complete examples, a package validator, a way to run your package in Perch, and a live link into Perch Studio.
Install
The server comes with Perch Studio (free on Steam). Nothing else to install: no Node, no npm, no git.
- Open Perch Studio.
- Help → Connect an AI Assistant…
- Press the button for your client: Claude Code, Claude Desktop or Cursor. Studio writes the client’s config to point at the server. Restart the client (Claude Desktop and Cursor read their config at start).
Any other MCP client: the same dialog shows the server’s path and a config snippet to copy. The server is perch-mcp.exe in the Perch Studio install folder; run it over stdio with no arguments.
What the assistant gets
| Tool | Gives the model |
|---|---|
perch_guide | The short authoring guide for the Lua API: package shape, the injected globals, widget.new with fields, display functions over refs, inputs as functions, perch.settings.declare with row objects, signals and requests, scopes, style. |
perch_vocabulary | The canonical vocabulary: the ui.* builders and their props, the enums, color roles, host functions, signals, scopes, surfaces, and the definition file. |
perch_docs | These pages: list, read one, or search. |
perch_examples | The builtin packages (media, clock, weather, launcher and more) with every file. |
perch_validate | Checks a package folder: manifest schema, entry present, every Luau file parses, a widget is declared, component names exist, no string where a ref or a function belongs. |
perch_run | Launches Perch with your package loaded, the same thing Perch Studio’s Run in Perch does. |
Perch Studio (the live link)
When Perch Studio is running, the server also drives it, the way the Roblox Studio MCP drives Roblox Studio. The studio_ tools work on the project that is open in the editor: writes go through the editor’s buffers, the real Perch loader and the Luau language server report back on every change, Run in Perch and its log are one call away, and the assistant can look at the window.
| Tool | What it does |
|---|---|
studio_status | Is Studio running, what project is open, its files, unsaved buffers, the loader verdict, Luau diagnostics. |
studio_open_project | Open a package folder in Studio. |
studio_read_file | A file as the editor has it (unsaved buffer wins). |
studio_write_file | Write a file through the editor: formatted, saved, re-validated by the real loader, re-checked by the language server; returns the verdict. |
studio_delete_file | Delete a file. |
studio_validate | The loader verdict + every language-server diagnostic for the project as it is in the editor. |
studio_open_file | Focus a file (and line) so the user sees it. |
studio_run | Run in Perch. |
studio_log | The package’s lines from Perch’s log since the last call. |
studio_screenshot | A screenshot of the Studio window (editor, problems, live preview). |
Nothing to configure: Studio publishes a loopback port and a per-launch token in its preferences folder; the server reads them. When Studio is not running the tools say so.
A first prompt
Using the perch tools, make me a widget that shows how many players are in my three favourite Steam games, one card each, picked in its settings. Validate it and run it.
The assistant reads the guide and the steam examples, writes the package, validates it, and launches Perch. With Perch Studio open it writes into the editor instead, and every write comes back with the loader’s verdict and the language server’s diagnostics, so it fixes its own mistakes before you look. The definitive verdict is still Perch’s own loader: open Settings, Installed mods, and read the card.