# Build tools Every tool and command an AI app gets on GoRunner’s build server. The server is `https://api.gorunner.io/mcp/build`, speaking MCP over streamable HTTP. An app gets the tools its permissions allow: 9, 10, 12 or 13. See [Choose what an AI app may do](https://docs.gorunner.io/mcp/permissions). The server tells each app to search apps, read the schema and validate before writing anything, then create, publish and run. The **Build a workflow** command adds: keep it a draft, run it as a test and read the run before suggesting publish. **In Embed:** The build server is `/mcp/embed//build`, offered only when the product turns on MCP building. ## Read Each one only reads. - `gorunner_search_pieces` · Always offered: **Search apps.** Finds the apps this installation runs: each one’s ID, name, category, whether it needs a connection, and its actions and triggers. If none matches, it says to call the service’s API with the HTTP Request app instead. Takes `query`, `category`. - `gorunner_get_piece_schema` · Always offered: **Get an app’s schema.** Reads the real fields of one action or trigger: names, types, choices and which are required. `narrow` picks the fields that apply for a value, such as a body type. Takes `pieceId` (required), `actionId`, `triggerId`, `narrow`, `version`. - `gorunner_list_workflows` · workflow:read: **List workflows.** Lists the workspace’s workflows, each with its whole definition, or without it when `view` is `summary`. 20 by default, up to 100. Takes `query`, `status`, `limit`, `view`. - `gorunner_get_workflow` · workflow:read: **Get workflow.** Reads one workflow’s draft and its `definitionRev`, which an update sends back as `expectedRev`. Takes `workflowId` (required). - `gorunner_validate_workflow` · workflow:read: **Validate workflow.** Checks a definition without saving it. Each problem says where it is and what would be allowed there. Pass `workflowId` when you check changes to an existing workflow, so each step is judged at the version it will run. One it can’t find is ignored, with a note. Takes `definition` (required), `workflowId`. - `gorunner_upgrade_code_step` · workflow:read: **Upgrade a Code step.** Converts one Code step of a draft from version 1.0.0 to 2.0.0 and returns the new step, what changed and what to review. It writes nothing: the app saves the result with `gorunner_update_workflow`. Takes `workflowId` (required), `step` (required). - `gorunner_list_connections` · connection:read: **List connections.** Lists the workspace’s connections: ID, name and app. Never their secrets. Takes nothing. - `gorunner_get_run` · run:read: **Get run.** Reads one run: its state, times, and each step’s input and output. `step` returns one step when the run is too big. Takes `runId` (required), `step`. - `gorunner_list_runs` · run:read: **List runs.** Lists recent runs, newest first. Production runs only, unless `environment` is `test` or `all`. Takes `workflowId`, `status`, `environment`, `limit`. ## Run Each call can send email, write to databases and call other services. - `gorunner_run_workflow` · workflow:run: **Run workflow.** Starts a run: `test` runs the draft, `production` the published version. It waits up to 20 seconds by default (0 to 30), then answers with the run. Send the same `idempotencyKey` when it retries. Takes `workflowId` (required), `environment` (required), `triggerData`, `waitSeconds`, `idempotencyKey`. ## Write Drafts change only when these run. Production changes only on publish. - `gorunner_create_workflow` · workflow:write: **Create workflow.** Makes a new workflow, always as a draft. It never changes an existing one. Takes `name` (required), `description`, `definition`. - `gorunner_update_workflow` · workflow:write: **Update workflow.** Replaces a draft’s whole definition. With `expectedRev`, it is refused if someone saved the workflow since. Production keeps running the published version. Takes `workflowId` (required), `definition` (required), `expectedRev`, `name`. - `gorunner_publish_workflow` · workflow:publish: **Publish workflow.** Publishes the draft, so production runs it. For a webhook trigger, this makes its address. It is refused, with the reason, if the workflow wouldn’t run. Takes `workflowId` (required). ## Workspaces Added when a connection reaches 2 or more workspaces. - `gorunner_list_workspaces` · 2 or more workspaces: **List workspaces.** Lists the workspaces the connection reaches, with which tools work in each. Every other tool then takes a `workspace` argument. ## Commands Apps list these as commands you pick, such as a slash menu. None of them publishes. - `build_workflow` · May write drafts: **Build a workflow.** Describe the automation in your own words. It is built, checked and test-run as a draft, and nothing goes live unless you say so. Takes `goal` (required). - `diagnose_failure`: **Diagnose a failed run.** Finds the latest failed run, of one workflow or any, reads what the failing step returned, and suggests a fix. Takes `workflow`. - `explain_workflow`: **Explain a workflow.** Explains what starts the workflow, what it does, and what it still needs before it can run. Takes `workflow` (required). ## What no tool does No tool deletes anything, creates a connection or reads a secret. An app can build a workflow that needs a connection you haven’t made: it saves as a draft, and publishing names the step that needs one. A tool calls the same API you do, with your permissions, and a refusal is the same. A production run an app starts shows the trigger **MCP** in Runs. One answer may be up to 96 KB. Past that, the app is told to narrow it: `step` for a run, `query` or `category` for apps, `query`, a smaller `limit` or `view: "summary"` for a list. A run too big to return has still started: the app is told its ID and not to start it again. `null` on an argument means the same as leaving it out, so a required one is refused as missing. Inside a value, such as a definition, it stays as it is. Each server’s tools count against your app’s own tool limit, so connect the build server only where you build. Related: [Turn your workflows into tools](https://docs.gorunner.io/mcp/workflows-as-tools) · [Workflow definition](https://docs.gorunner.io/api/workflow-definition) · [Idempotency](https://docs.gorunner.io/api/idempotency) · [Sign-in for developers](https://docs.gorunner.io/mcp/oauth) Source: https://docs.gorunner.io/mcp/build-tools