Build tools

Every tool and command an AI app gets on GoRunner’s build server.

Cloud, Self-hosted and Embed

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.

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/<account>/build, offered only when the product turns on MCP building.

Read

Each one only reads.

gorunner_search_piecesAlways 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_schemaAlways 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_workflowsworkflow: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_workflowworkflow:read

Get workflow. Reads one workflow’s draft and its definitionRev, which an update sends back as expectedRev.

Takes workflowId (required).

gorunner_validate_workflowworkflow: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_stepworkflow: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_connectionsconnection:read

List connections. Lists the workspace’s connections: ID, name and app. Never their secrets.

Takes nothing.

gorunner_get_runrun: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_runsrun: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_workflowworkflow: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_workflowworkflow:write

Create workflow. Makes a new workflow, always as a draft. It never changes an existing one.

Takes name (required), description, definition.

gorunner_update_workflowworkflow: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_workflowworkflow: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_workspaces2 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_workflowMay 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.