PIES Studio 1.9 · Documentation
If you already work with an AI coding agent, it can build and run PIES Studio applications for you. You describe the application. The agent creates the tables, sample rows, screens, a dashboard and the menu, and then opens the running application and the Studio editor so you can see what it built.
This works with PIES Studio Hobby on your own computer and with a PIES Studio Enterprise server, and with these agents:
| Provider | Agents | Set-up |
|---|---|---|
| Anthropic (Claude) | Claude Code, Claude Desktop | Claude |
| OpenAI | Codex CLI, Codex in VS Code | OpenAI |
| Cursor | Cursor's agent | Cursor |
| Any other agent that supports MCP | for example VS Code with GitHub Copilot, Windsurf | Other agents |
This page is for people who already use one of these agents. If you have not used one before, start with the Quickstart and build inside Studio instead.
PIES Studio runs a Studio MCP server. MCP (Model Context Protocol) is the standard way AI agents connect to tools. Your agent connects to that server and, through it, reads and changes your applications using the same rules that apply when you edit by hand.
Measured. Same brief, same model, stack pinned: building through PIES used 41% of the output tokens, 72% of the cost and 43% of the agent time of the agent writing the code itself, with two gaps we show. The method, both pairs of runs and the gaps are in Your agent plans, PIES writes the code: a measured comparison.
Every agent below needs one address, the MCP URL, and on Enterprise also a token.
| PIES Studio Hobby | PIES Studio Enterprise | |
|---|---|---|
| MCP URL | http://127.0.0.1:19085/agent/sse | https://<your-studio-address>/mcp/agent/sse |
| Token | Not needed. The server listens only on your own computer. | Needed. You create your own personal token in Studio. Your agent signs in as you, and sees only your organisation's applications. |
| Where to find it | AI Settings → Connect your coding agent, with a Copy button | AI Settings → Connect your coding agent: the address, Create token, and a Copy button. See Enterprise. |
| Must be running | The Hobby app must be open. The server runs only while it is. | Always on. |
/agent/sse or /sse? Use /agent/sse. It gives the agent the compact set of tools it needs to build, about 2,900 tokens per turn instead of the full Studio set, so builds are cheaper and faster. /sse gives the full set used by PIES AI itself; it still works, for example with older set-ups that use it.
Ports. Hobby uses port 19085. If you started Hobby with PIES_DESKTOP_PORT_OFFSET=N, add N: an offset of 3000 means http://127.0.0.1:22085/agent/sse. The Connect your coding agent card always shows the address in use.
The Connect your coding agent card has a tab for each agent: Claude Code, Claude Desktop, Codex and Cursor. Each tab shows the ready-made configuration for your edition. On Enterprise, select Create token and the card puts your new token into every snippet, so you can copy it as it is.
In the examples below, replace the Hobby address with your Enterprise address when you use Enterprise, and add the token line where shown.
In Claude Code, run:
/plugin marketplace add pies-io/claude-plugins
/plugin install pies
The plugin connects to Hobby and adds three commands: /pies-build, /pies-run and /pies-explain (see The three commands).
With a Hobby port offset, set the address before you start Claude Code:
PIES_MCP_URL=http://127.0.0.1:22085/agent/sse claude
For Enterprise, set your address and your token before you start Claude Code; the plugin sends the token with every request:
PIES_MCP_URL=https://<your-studio-address>/mcp/agent/sse PIES_MCP_TOKEN=<your token> claude
Without the commands, connect with one line.
Hobby:
claude mcp add --transport sse pies http://127.0.0.1:19085/agent/sse
Enterprise:
claude mcp add --transport sse pies https://<your-studio-address>/mcp/agent/sse --header "Authorization: Bearer <your token>"
Run claude mcp list to check that pies shows as connected.
Claude Desktop starts its tools as local programs, so it connects through the small mcp-remote bridge. You need Node.js 18 or later.
Open Settings → Developer → Edit Config and add pies to claude_desktop_config.json:
{
"mcpServers": {
"pies": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://127.0.0.1:19085/agent/sse"]
}
}
}
For Enterprise, use your address and add the token:
"args": ["-y", "mcp-remote", "https://<your-studio-address>/mcp/agent/sse",
"--header", "Authorization: Bearer <your token>"]
Restart Claude Desktop. The PIES tools appear under the tools icon in the message box.
Claude on the web (claude.ai) cannot reach Hobby, because Hobby's server is only on your computer. Use Claude Code or Claude Desktop.
Codex connects through the same mcp-remote bridge. You need Node.js 18 or later. Add this to ~/.codex/config.toml:
[mcp_servers.pies]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:19085/agent/sse"]
For Enterprise, use your address and add the token:
[mcp_servers.pies]
command = "npx"
args = ["-y", "mcp-remote", "https://<your-studio-address>/mcp/agent/sse", "--header", "Authorization: Bearer ${PIES_MCP_TOKEN}"]
env = { PIES_MCP_TOKEN = "<your token>" }
Start Codex and run /mcp to check that pies is listed. Codex has no PIES commands; ask in your own words, for example "Use the pies tools to build a job tracker with customers, jobs and a dashboard."
ChatGPT (web and desktop) cannot reach Hobby, because Hobby's server is only on your computer. Use Codex.
Add pies to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project.
Hobby:
{ "mcpServers": { "pies": { "url": "http://127.0.0.1:19085/agent/sse" } } }
Enterprise:
{
"mcpServers": {
"pies": {
"url": "https://<your-studio-address>/mcp/agent/sse",
"headers": { "Authorization": "Bearer <your token>" }
}
}
}
Open Cursor Settings → MCP: pies should show a green dot and its tools. Use the agent in Agent mode and ask in your own words, for example "Use the pies tools to build…".
Any agent that supports MCP over SSE can connect with the address above, and the Enterprise token as an Authorization: Bearer <token> header. An agent that only starts local programs can use npx -y mcp-remote <address> as shown for Claude Desktop.
These come with the Claude Code plugin. With any other agent, ask for the same thing in your own words.
| Command | What it does |
|---|---|
/pies-build "<what you want>" | Builds the application: tables with sample rows, list screens with filters, a dashboard with figures and charts, and the menu. It sends one complete brief that is checked before anything is created, and carries the build through without asking you questions along the way. |
/pies-run | Builds the preview, opens the running application in your browser and opens it in the Studio editor. In the application, choose Sign in with PIES Studio. |
/pies-explain | Asks the application what it does: what each screen shows, which tables it reads and writes, and what each button does. Use it to look over what the agent built. |
Your agent asks you to approve its tool calls in the usual way.
/pies-build "a job tracker with customers, jobs with status and due date, and a dashboard"
/pies-run
/pies-explain
Other ideas: "an equipment register with locations and service dates", "a sales pipeline with companies, deals by stage and a dashboard of value by stage".
The Studio MCP server tells your agent how PIES applications are described before it builds anything, so the agent gets the build right first time instead of finding the format by trial and error. Agents that support MCP resources and prompts read these on their own:
| Name | What it is |
|---|---|
pies://spec | A compact spec sheet: the shapes of a brief, a table, a screen, a function and a dashboard; the allowed layouts, widget and chart types and field types; and the rules Studio checks, such as a chart having to use columns from its own table. It is generated from the same checks Studio runs, so it always matches what Studio accepts. |
pies://app/<id>/summary | A short description of an existing application: its tables and columns, screens, functions, events and menu. Agents read it before changing an application instead of reading the whole definition. |
build-app (a prompt) | The recommended sequence, with a worked example: send one complete brief to build the application, then fix anything left over in one batch. |
The brief's shape comes with the tool. build_from_brief describes every field of a brief itself, so an agent can send a brief straight away without reading pies://spec first. Common ways of writing the same thing are understood: a dashboard can be given as figures counted by a field plus lists, the number of sample rows can be given per table, and a field Studio does not know is skipped with a warning instead of stopping the build. A figure counted by a choice field, such as status, becomes one figure per value, and an "overdue" list shows only items past their due date that are not done.
One reply says what was built. When the build finishes, the reply lists the tables with their row counts, the screens, the menu and the preview address. When nothing is left for the agent to do, the build is finished, so the agent does not spend turns reading the application back.
A brief with real mistakes is refused whole. Before it builds, Studio checks the agent's brief against the same rules. If anything is wrong, such as an unknown theme, an unknown field type or a reference to a table that does not exist, the agent gets every problem in one reply and nothing is created. It fixes them all and sends the brief again, so you never end up with a half-built application.
The agent chooses the look. A brief can say how the application should look, not only what it holds. The agent can name the app's theme (a palette direction, a light or dark look and how dense the screens are) and, for each screen, the layout it wants: a header or hero, a row of key figures, a grid of charts, cards instead of a plain table, a detail panel, what an empty list says, and icons. Every screen goes through the same designed layout path that PIES AI uses in Studio, lists, forms and detail screens as well as the dashboard. The spec sheet shows the design fields with a worked example of a polished screen.
Good defaults when the agent says nothing about design. One theme is used across every screen. A column that points at another table shows the related record's name, not its number, and the row number used to open a record is hidden from the table. A list, form or detail screen whose header has no colour gets a compact page header (the title and subtitle on the page background, with the main button on the right) so the table gets the space; dashboards and landing pages keep their coloured banner. A colour the agent names always wins.
The agent looks at what it built. review_screens returns a small screenshot of each screen with a design score and notes. The agent fixes weak screens in one compile_specs batch and reviews again. The build-app prompt recommends at most two rounds, so reviewing does not eat the savings.
PIES AI follows the same rules. When PIES AI builds in Studio, it takes the reserved column names and the rules Studio checks from the same spec sheet, so what it builds and what your coding agent builds are checked against one set of rules.
These resources and the prompt do not add to the list of tools your agent loads.
These are the tools your agent sees on /agent/sse. You do not call them yourself; the agent picks them. They are listed so you know what you are approving.
| Tool | What it does |
|---|---|
whoami | Says who the agent is acting as. On Enterprise, this is you and your organisation. |
list_workspaces, list_apps | Lists your workspaces and the applications you can open. |
create_app | Creates a new, empty application in a workspace. |
get_app_summary | Counts and names an application's screens, events, functions and tables. |
build_from_brief | Builds a whole application from one brief: tables and sample rows, list, form and detail screens with their functions and events, a dashboard, the menu, then a build report. |
plan_build | Turns a request into a build plan before anything is created. |
get_spec_schema | The exact shape of a table, screen, list-and-form or function description for this application, with its real table and column names. |
compile_data_spec | Creates tables, links between them, and sample rows. |
compile_screen_spec | Creates a laid-out, themed screen from a list of sections (figures, charts, tables, forms, text, buttons). |
compile_crud_spec | Creates list, form and detail screens for a table, with the functions and events behind them. |
compile_function_spec | Creates a backend function from steps (find, create, update, delete, if, loop, send email, call an API, set a variable, return). |
compile_event_spec | Creates what happens when a button is clicked, a field changes or a screen loads. |
compile_edit_spec | Makes small changes to an existing screen: text, style, columns, chart type, labels. |
compile_specs | Runs several of the above in one call, in order. |
save_generated_menu | Saves the application's menu. |
get_build_report | Reads what the last build reported, with each error tied to the screen or function that caused it. |
review_screens | Renders each screen and returns a small screenshot, a design score and notes per screen, so the agent can fix weak screens and check again. |
delete_screen, delete_table, delete_function | Removes one item. Studio takes a version snapshot first, so you can go back. |
Every change goes through the same checks as an edit in Studio, and every change can be undone from the application's version history.
It can create an application, its tables and sample rows, its screens, dashboard and menu. It can also change an existing application, and explain one.
It cannot do anything your edition does not offer, or anything you could not do yourself. On Hobby, Hobby's limits apply (see Hobby). On Enterprise, the agent acts as you: it sees only your organisation's applications and has your permissions. What it builds is an ordinary PIES Studio application. You can open it, change it by hand or with PIES AI, and download its source.
On Enterprise the Studio MCP server runs on the server, so two things are different from Hobby:
/mcp/: https://<your-studio-address>/mcp/agent/sse. The Connect your coding agent card in AI Settings shows it. Your computer must be able to reach Studio, for example on the company network or VPN. Every request needs a token.401 authorization required.To get a token, open AI Settings → Connect your coding agent and select Create token. The token is personal: it belongs to you and your organisation. Copy it when it is shown and keep it like a password. You can revoke a token at any time; an agent using a revoked token is refused straight away. Create a new token if you lose one.
Administrators: PIES_MCP_AUTH=enforce makes the server refuse every request without a token, including from the server itself. Do not set PIES_MCP_AUTH=off on a server other people can reach.
The agent cannot connect, or lists no pies tools.
401 authorization required or "expired or malformed authorization token". Enterprise only. The token is missing, mistyped or revoked. Create a new one in AI Settings → Connect your coding agent and update your configuration.
npx: command not found (Claude Desktop, Codex). Install Node.js 18 or later, then restart the agent.
The agent has dozens of PIES tools and builds are slow or costly. It is connected to /sse. Change the address to end in /agent/sse.
"client_id" is needed. You are connected to an Enterprise server without a token, on a set-up that allows that. Use a token; the organisation then comes from it.
Tool calls time out for a few minutes after the menu is saved. This happens on older Hobby builds. Your work is saved. Update Hobby, or wait and carry on.
The preview does not open. The first preview build takes a few minutes. /pies-run shows the last error lines if a build fails. You can also open the application in Studio and choose Build.
Hobby: the Studio MCP server stays on your computer. Enterprise: it stays on your server and network. In both, nothing leaves except what your agent sends to its own model provider (Anthropic, OpenAI, Cursor or another), under that provider's terms. That includes your prompt and the parts of your application the agent reads. If that is not acceptable for your data, build inside Studio with PIES Private AI instead.