Action Apps: Web Form, REST API, CLI and MCP Tool from One Function
Actions let an app expose an autogenerated UI for simple backend actions. Where an existing CLI application or API needs to be exposed as a web app, actions provide an easy solution. An app can define one or more actions. Each action has a unique path, which must not conflict with any other route defined for the app.
Every action is reachable in four ways, with no change to the app code:
| Surface | Where | Details |
|---|---|---|
| Form UI | The action path under the app path | Sample Action |
| REST API | /api under the app path | REST API |
| CLI | openrun action run, locally or through a remote CLI | Command Line |
| MCP tools | /mcp under the app path, and /_openrun/app_mcp for all apps | MCP Tools |
See weather app code:demo for an example of using Actions. For actions as team operations tools, kept in git and run from the form, the CLI and by AI agents, see the Jenkins and Rundeck alternative use case.
Sample Action
First, define the parameters to be exposed in the form UI. Create a params.star file with the params. For example,
param("repo", description="The GitHub repository to look up", default="openrundev/openrun")
param("show_issues", type=BOOLEAN, description="Whether to show the open issues count", default=True)This app defines a run handler which calls the GitHub API for the specified repository, using the http plugin, and returns the stats as text.
load ("http.in", "http")
def run(dry_run, args):
if "/" not in args.repo:
return ace.result("Validation failed", param_errors={"repo": "expected owner/name format"})
repo = http.get("https://api.github.com/repos/" + args.repo).value.json()
out = ["Stars: %d" % repo["stargazers_count"], "Forks: %d" % repo["forks_count"]]
if args.show_issues:
out.append("Open Issues: %d" % repo["open_issues_count"])
return ace.result("Repo info for " + args.repo, out)
app = ace.app("Repo Info",
actions=[ace.action("Repo Info", "/", run, description="Show the GitHub stats for the specified repository")],
permissions=[
ace.permission("http.in", "get", ["regex:^https://api\\.github\\.com/.*"]),
],
)The app, when accessed, shows a form for the params, with the action output displayed below it:

Action Definition
An action is defined with the ace.action struct. Its fields are:
| Property | Optional | Type | Default | Notes |
|---|---|---|---|---|
| name | false | string | The action name | |
| path | false | string | The path to use within app path | |
| run | false | function | The function to run on execution | |
| suggest | true | function | none | The function to run on suggest |
| description | true | string | none | The description for the action |
| hidden | true | list strings | none | The params which should be hidden in the UI for this Action |
| show_validate | true | boolean | False | Whether to show a Validate option for this action |
| permit | true | list string | [] | List of custom RBAC permissions, any one of which need to be granted for the user to allow this action |
| is_async | true | boolean | False | True runs the handler in the background, see Async Actions |
| timeout | true | string | none | Timeout of an async run, a Go duration like "2h"; defaults to the app’s action.run_timeout |
| read_only | true | boolean | none | True declares that the action changes nothing, see Side-effect Hints |
| destructive | true | boolean | none | True declares that the action makes changes which may not be reversible |
| idempotent | true | boolean | none | True declares that running the action again with the same args has no further effect |
| open_world | true | boolean | none | True declares that the action reaches outside the app (a web API, a mail sender) |
- The name and description are shown in the app UI.
- The app params are displayed in a form:
BOOLEANtypes are checkboxes, others are text boxes. - When the form is submitted, the
runfunction is called with the params as theargsargument. The response returned by the handler is shown on the UI. hiddenhides params for specific Actions. Set it to the list of params to hide, for examplehidden=["param1"].
args argument to get the values from the form. Referencing param gives the app’s configured parameter values, not the values submitted in the form.Action Result
The handler returns an ace.result struct. Its fields are:
| Property | Optional | Type | Default | Notes |
|---|---|---|---|---|
| status | true | string | The action status message | |
| values | true | list | [] | The actions output, list of strings or list of dicts |
| report | true | string | ace.AUTO | The type of report to generate. Default is ace.AUTO, where it is selected based on response type. Other options are ace.JSON, ace.TEXT, ace.TABLE, ace.DOWNLOAD and ace.IMAGE. Any other value is a custom template name. |
| param_errors | true | dict | {} | The validation errors to report for each param. The key is the param name, the value is the error message |
| stream | true | object | none | The response of a plugin call made with stream=True, see Streaming Output. Cannot be combined with values, report or param_errors |
Validating Params
The run handler can validate the parameters and return the errors, for one or more params:
def run(dry_run, args):
if args.dir == "." or args.dir.startswith("./") or args.dir == ".." or args.dir.startswith("../"):
return ace.result("Validation failed", param_errors={"dir": "relative paths not supported"})
if dry_run:
return ace.result("Validation successful")
# Actual code for run handlerIf the action definition has show_validate=True, a Validate option shows up in the UI. It invokes the run handler with dry_run=True. The run handler should return after the param validation when dry_run is true.
Suggest Handler
If a suggest handler is defined for an action, a Suggest button shows up in the UI. Suggest populates param values dynamically. For example, if the app has three params A, B and C, all empty initially, the first suggest can do return {"A": ["avalue1", "avalue2", "avalue3"]}, which populates the A param with a dropdown. A subsequent suggest call can populate the value for B, with a list of options or with an actual value. The suggest handler is optional. A sample suggest handler is
def suggest(args):
if not args.A:
alist = []
res = store.select(table.adata, {})
for aval in res.value:
alist.append(aval.name)
return {"A": alist}
else:
if not args.B:
res = store.select_one(table.adata, {"A": args.A})
return {"B": res.value.bval}
return {}See weather app code:demo for an example of using suggest.
Report Types
The response values can be a list of strings or a list of dicts. With the default ace.AUTO, the report type is selected from the values:
| Values | Report | Notes |
|---|---|---|
| List of strings | TEXT | |
| List of dicts, all values of the first row simple types | TABLE | The fields of the first row are the columns. Extra fields in subsequent rows are ignored |
| List of dicts, any value of the first row a complex type (like dict or list) | JSON | A JSON tree representation of each row is shown |
The report type can be set to a specific type instead of using AUTO.
Streaming Output
A run handler that starts a long running command can stream the command’s output to the page as it is produced, instead of returning it after the command exits. Call exec.run (or container.run) with stream=True, check the call for a startup error, and return the response object in the stream property of ace.result:
load("exec.in", "exec")
def build_run(dry_run, args):
if not args.target:
return ace.result("Validation failed", param_errors={"target": "target is required"})
if dry_run:
return ace.result("Ready to build " + args.target)
ret = exec.run("make", [args.target], cwd="/srv/app", stream=True)
if ret.error:
return ace.result("Could not start make: " + ret.error)
return ace.result("Building " + args.target, stream=ret)
app = ace.app("builder",
actions=[ace.action("Build", "/", build_run, show_validate=True)],
permissions=[ace.permission("exec.in", "run", ["make"])])- On the page: the status text shows immediately and a log pane below it fills as the command prints. Terminal colors and progress bar updates render as in a terminal.
- On exit: the pane reports the exit status, and a non-zero exit marks the status line as an error. Closing the page stops the command.
- Shorthand: returning the stream response object directly from the handler is the same as
ace.result("", stream=ret). - No values, no param errors: a streamed result has no
valuesorreport(the output is the report) and cannot carryparam_errors. Do the validation, and return, before starting the command. A stream returned whendry_runis true (the Validate button) is an error. - Decided per run: nothing is declared on
ace.action. The handler decides per run, so a validation failure still returns an ordinary result. - Audit: the audit event for the action records success only when the command exits with status 0.
See the async_action example code for a runnable sample: its Build action streams a shell loop’s output live, as an async action whose run can be watched and canceled from the run page, beside a sync Ping action for comparison.
Async Actions
A sync action runs its handler inside the request: the browser waits, the server’s request timeout applies (three minutes), and closing the page cancels a streamed command. An action which takes longer, or whose runs should be kept, is declared with is_async=True:
load("exec.in", "exec")
def rebuild(dry_run, args):
if not args.target:
return ace.result("target is required", param_errors={"target": "required"})
if dry_run:
return ace.result("Ready to rebuild " + args.target)
return exec.run("make", ["-C", "/srv/site", args.target], stream=True)
app = ace.app("site",
actions=[ace.action("Rebuild", "/rebuild", rebuild, is_async=True, timeout="2h",
show_validate=True, description="Rebuilds the site (takes 10-30 minutes)")],
permissions=[ace.permission("exec.in", "run", ["make"])])The run page
- The form of an async action has a Start button. It starts a run: the handler executes in the background on the server, as the submitting user, and the run page opens.
- The run page shows the status, the args and the output of a streamed command as it is produced (the page can be closed and reopened). Once the run ends, it shows the result rendered as a sync action renders it. A running run can be canceled from its page, and Run again opens the form with the run’s args.
- Run History, linked under the action title, lists the runs of the action, newest first: their status, the user who started them, their duration and one column per arg. The list filters by status and by text:
name=valuefor an exact arg, a bare word for text in any arg value, the result status or the failure message.
| Run status | Meaning |
|---|---|
running | The handler is executing |
succeeded | The run ended with a result, or the streamed command exited with code 0 |
failed | The handler failed, returned param_errors or the streamed command exited with a non-zero code |
timed_out | The run exceeded its timeout (or the app’s action.run_timeout) |
canceled | The run was canceled from the run page, the CLI, the REST API or an MCP tool |
lost | The node executing the run stopped. Marked after a minute; the run can be started again |
Writing the handler
The handler is written as for a sync action:
- It returns a stream (the run’s output is the command’s output, exit code 0 is success) or an
ace.resultwith values and a report, which is stored with the run. print()calls in the handler go to the run output.- A result with
param_errorsfails the run. Validate the args withshow_validate=Trueor thedry_runbranch, which remain synchronous. - Password params are not recorded with the run. File upload params are recorded by file name.
Run settings
The runs are recorded in the metadata database, per app instance (the stage instance has its own runs). The settings below are [app_config] settings in the server config, overridable per app with openrun app update conf --promote 'action.retain_runs=20' /site:
| Setting | Default | Meaning |
|---|---|---|
action.retain_runs | 100 | Runs kept per app instance, across the app’s actions |
action.output_head_bytes | 10MB | For a streamed command, the first bytes of the output kept |
action.output_tail_bytes | 10MB | The last bytes of the output kept. The bytes between head and tail are dropped, with a marker |
action.result_max_bytes | 100MB | For a values result, the JSON kept. Whole rows beyond that are dropped and the run says so |
action.display_rows | 1000 | Rows the run page renders. The stored result is offered as a download |
action.run_timeout | 1h | Timeout of runs without their own timeout |
action.max_async_runs | 20 | Runs of an app instance executing at once on a node |
action.max_wait_secs | The longest wait the REST API ?wait= accepts |
Nodes, reloads and audit
- A run executes on the node which accepted it. If the node stops, the run is marked
lostafter a minute and can be started again. - A reload or update of the app while a run executes lets the run finish on the version it started with.
- Every run writes an
actionaudit event with the operationrun_finish, the run id and its status, in addition to the submission’s event.
Runs over the REST API
Through the REST API the run endpoint of an async action answers 202 with the run_id and the run url. The runs are managed with:
| Endpoint | Notes |
|---|---|
GET /api/runs/<id> | The run with its result. ?wait=30s waits for the end, up to action.max_wait_secs |
GET /api/runs/<id>/output?since=<offset> | The output |
GET /api/runs?action=<path>&status= | Lists the runs |
POST /api/runs/<id>/cancel | Cancels a run |
The CLI and the MCP tools have the same operations.
Side-effect Hints
An action can declare what its run does to the world, with the read_only, destructive, idempotent and open_world fields of ace.action:
app = ace.app("orders",
actions=[
ace.action("Order Report", "/report", report, read_only=True),
ace.action("Cancel Order", "/cancel", cancel, destructive=True, description="Cancels the order and refunds it"),
ace.action("Set Flag", "/flag", set_flag, destructive=False, idempotent=True),
])- Informational only: the hints never change who may run an action (
permitand RBAC do) or how it runs. - Where they show: a
Hintscolumn inopenrun action list, aHints:line inopenrun action show, thehintsfield of thelist_actionsandget_actionmanagement APIs, and the tool annotations of the action’s MCP tool (readOnlyHint,destructiveHint,idempotentHint,openWorldHint), which AI clients use to decide when to ask the user before a call. read_only=Trueimplies not destructive and idempotent.- An action which declares none of the fields has no hints and no tool annotations, and clients treat it as they did before hints existed.
destructive=Truehas two visible effects: the action page shows a Destructive badge next to the action name, and MCP clients which support elicitation are asked to confirm the call before the action runs (see MCP Tools). The CLI and the REST API run a destructive action at once, as they run any other action.
Custom Templates
If the report type is set to any value other than ace.AUTO, ace.TEXT, ace.JSON, ace.TABLE, ace.DOWNLOAD or ace.IMAGE, that value is treated as a custom template. The template is defined in a *.go.html file, referenced by file name or by template/block name. See template for details.
For styling, OpenRun uses DaisyUI by default, so default styles are reset. The custom template can use inline styles or TailwindCSS/DaisyUI. For DaisyUI, run the app in dev mode first so the style.css is generated. See styling for details.
See dictionary code:demo for an actions example app which shows different type of reports.
Param Value Selector
A param can offer a list of values for the user to choose from, through an options param. options_ is a special param name prefix: if param1 should show up as a selector, define another param named options_param1, of type LIST, whose default value holds the values to show in the dropdown. For example
param("param1", description="The param1 description", default="option1")
param("options_param1", type=LIST, description="Options for param1", default=["option1", "option2"])In the UI, options_param1 is not displayed. param1 is shown as a searchable dropdown, having option1 and option2 as options. Typing in the field filters the options. By default the dropdown is strict: the value has to be one of the options (enforced in the UI and also on the server for configured option lists). To allow free text entry in addition to the listed options, set display_type=COMBO on the param:
param("param1", description="The param1 description", default="option1", display_type=COMBO)
param("options_param1", type=LIST, description="Options for param1", default=["option1", "option2"])- The
options-param1naming format (with a dash) is also supported, for backward compatibility. The underscore format is preferred since it is a valid Starlark identifier, so the value stays accessible in the app code asparam.options_param1. - The same applies to dropdowns populated by a suggest handler: values suggested as a list show as a strict searchable dropdown unless the param has
display_type=COMBO. See dictionary for an app which uses options. - An options param is used instead of configuring the options on the param directly so that the options can be set per installation, without maintaining different copies of the app code. For example, the following adds a new
options3option:
openrun app create --approve --param options_param1='["option1", "option2", "options3"]' /mycode /myappDisplay Types
For string type params, the display_type property sets the form field:
display_type | Field |
|---|---|
| not set | A text input box |
FILE | A file upload input, see File Handling |
PASSWORD | A password input |
TEXTAREA | A text area |
COMBO | A dropdown param (one with a value selector or suggest provided options) which accepts free text entry in addition to the listed options. Without it dropdown values are restricted to the list |
File Handling
For the FILE display type, the Action app user can upload a file. The file is uploaded to a temp file on the server and the file name is available through args.param_name, to be processed as required from disk. Multiple FILE type params are supported, each param can upload one file only. The temp files are deleted at the end of the handler function execution.
Action request bodies are capped by default at 33554432 bytes. To change this globally, update app_config.action.max_request_body_bytes in openrun.toml. To override it for one app, run:
openrun app update conf --promote 'action.max_request_body_bytes=67108864' /myappTo return a file as output for the action, use the fs.serve_tmp_file API, which makes a file on disk available through an API. Use report=ace.DOWNLOAD in the ace.result to generate a file download link. See number_lines app code:demo for an example of using this API.
Files from the system temp directory and from /tmp are accessible by default for the serve_tmp_file API. The file is deleted from disk by default after the first download. The directories are configured at the system level with
[app_config]
fs.file_access = ["$TEMPDIR", "/tmp"]and at the app level with
openrun app update conf --promote fs.file_access='["/var/tmp", "$TEMPDIR", "/tmp"]' /myappREST API
Every action app automatically exposes a REST API in addition to the form UI, with no change required in the app code. The API is mounted at the reserved /api path under the app path (an action cannot be defined at the /api path). Authentication and authorization work the same as for the UI: the app level auth applies, and per-action permit RBAC checks are enforced.
| Endpoint | Method | Notes |
|---|---|---|
/app_path/api | GET | List the actions available in the app, with their API paths (the run, validate and suggest path of each action) |
/app_path/api/openapi.json | GET | OpenAPI 3.0 spec for the actions the current user has access to |
/app_path/api/actions/<action> | GET | Get the param definitions (name, type, default, options) |
/app_path/api/actions/<action> | POST | Run the action |
/app_path/api/suggest/<action> | POST | Run the suggest handler |
/app_path/api/validate/<action> | POST | Run the handler with dry_run=True |
<action>is the action path. For an action at path/, the run endpoint is/app_path/api/actionsand the validate endpoint is/app_path/api/validate. For an action at path/list, they are/app_path/api/actions/listand/app_path/api/validate/list.- The
operationIdvalues in the OpenAPI spec arerun_<name>,validate_<name>,suggest_<name>andschema_<name>, where<name>is the action name used by the command line and the MCP tools: the action path with/replaced by_, and for the action at/its name in lowercase (run_cancel_orderfor theCancel Orderaction).
Request body
The run/suggest/validate endpoints accept a JSON body with the param values, using native JSON types ({"dir": "/tmp", "detail": true}):
- String values are coerced to the param type, same as form submissions.
- Values for params with a selector must be one of the configured options unless the param uses the
COMBOdisplay type. - Params missing from the body use their app level values, including
BOOLEANparams (unlike the form UI, where a missing checkbox means false). - Hidden params and unknown params are rejected with a 400 error.
- Form encoded and multipart bodies are also accepted. Params with
FILEdisplay type must be submitted as multipart file uploads and cannot be set through JSON.
Response
| Status | Body |
|---|---|
| 200 | A JSON object with status, values and report (the resolved report type, such as TEXT, TABLE or JSON) |
| 202 | The run_id and run url of an async action |
| 400 | A hidden or unknown param in the body |
| 422 | Param validation errors, with a param_errors object |
| 500 | A handler failure, with an error message |
$ curl -X POST -H "Content-Type: application/json" -d '{"dir": "/var/log"}' https://example.com/myapp/api/actions
{"report":"TEXT","status":"File listing for /var/log","values":["total 0\n..."]}An action which streams its output responds with chunked text/plain instead:
- The body is the command output as it is produced (
curl -Nshows it live). - The result status text is in the
OpenRun-Action-Statusresponse header. - The command’s exit status is in the
OpenRun-Exit-StatusHTTP trailer, sent when the stream ends. A missing trailer means the stream was cut before the command exited. - Param validation errors and handler failures keep the JSON shapes above.
$ curl -sN -X POST -H "Content-Type: application/json" -d '{"target": "web"}' https://example.com/builder/api/actionsCommand Line
Actions can be listed and run with the openrun action commands, from the server machine or through a remote CLI. No change is required in the app code.
openrun action list [<appPathGlob>] # the actions you can run
openrun action show <appPath> [<action>] # the params, and a usage line to copy
openrun action run <appPath> [<action>] [name=value ...] # run the action
openrun action validate <appPath> [<action>] [name=value ...] # run the handler with dry_run=True
openrun action suggest <appPath> [<action>] [name=value ...] # run the suggest handler
openrun action openapi <appPath> # the OpenAPI spec of the REST API<action>is the name shown in theActioncolumn ofaction list: the action path with/replaced by_(/orders/cancelisorders_cancel), or for the action at/, its name in lowercase (Cancel Orderiscancel_order). The action path (like/cancel) is accepted too.<action>can be left out for an app with one action.--stageuses the staging instance of the app.
$ openrun action run /orders list_orders count=2 status=closed
Listed 2 orders
id rush status
1 false closed
2 false closedPassing args
- Args are passed as
name=value. The value is converted to the type of the param as a form value would be (true/falseforBOOLEAN, a JSON value forLISTandDICT). - Params which are not passed use the value configured for the app.
--json '{"count": 2}'passes typed args as a JSON object (--json=@filereads the object from a file,--json=-from stdin).name=valueargs override its entries.name=@fileuploads the file for a param with theFILEdisplay type.
Output
The result values are written to stdout and the status line to stderr (--quiet turns it off), so the output can be piped. The values are shown the way the action reports them: a table for TABLE, lines for TEXT, formatted JSON for JSON. --format json, jsonl or csv converts them:
openrun action run -q --format jsonl /orders list_orders status=open | jq .idFor an action which returns files (the DOWNLOAD and IMAGE report types), the files are listed with their url; --output saves them:
openrun action run -o report.pdf /orders report month=2026-08 # one file, saved under the given name
openrun action run -o ./out/ /orders charts # into a directory, under the names the action gave the files
openrun action run -q -o - /orders export | head # to stdout- A directory is required when the result has more than one file.
- The CLI has no browser session with the app, so a file whose url is within the app (a file from
fs.serve_tmp_file, a static file of the app) is fetched through the OpenRun API as the calling user, under the same checks as running the action. The rules of the file apply: asingle_accessfile is removed once it has been saved. Any other url is fetched directly, without credentials. - The output of an action which streams a command is written as it is produced.
action suggestprints the suggested values asname=valuelines, the formaction runtakes them in.
| Exit code | Meaning |
|---|---|
| 0 | The action ran |
| 2 | Param validation errors, printed as error: param <name>: <message> |
| 1 | Any other failure: invalid args, not authorized, a handler error |
| other | For a streamed command, the exit code of the command |
Async actions
openrun action run of an async action starts the run and prints its id. --wait polls the run until it ends and prints the result as for a sync action (with the same exit codes); --follow prints the output of a streamed command as it is produced and then the result. Both report the run id on stderr as soon as the run starts, so it is at hand if the command is interrupted. The runs are managed with:
openrun action runs /site [rebuild] [--status failed] [--limit 20] # the runs of the app (or one action), newest first
openrun action output <run-id> [--follow] # the stored output (the first and last 10MB), or the result values as JSON
openrun action cancel <run-id> # stop a running runCtrl-C while following leaves the run running. openrun action show reports async actions, and openrun action list -f json carries async.
Who the action runs as
The CLI runs actions through the management API as the calling user, under the same checks the form UI applies to that user:
- The user comes from the login the app’s
authsetting names. A user logged in asbuiltin:bobcannot run the actions of an app with--auth saml_okta, even if an RBAC group grant covers both identities. Apps withauthnoneaccept any user; apps usingsystemor client certificate auth can be used by the admin only. - The user has the
app:accesspermission on the app. - The user has one of the permissions in the action’s
permitlist.
action list shows only the actions which pass all three checks. Runs are recorded in the audit log under that user, with the operation cli_execute, cli_validate or cli_suggest (the form UI records execute, validate and suggest, the REST API api_execute, api_validate and api_suggest).
What the commands load
Listing actions does not load or start apps: the actions of an app version are stored with its metadata when the app is created, reloaded or promoted. Apps in dev mode are listed from their current source. action show loads the app definition, and only running an action (or its suggest handler) starts the app’s container.
On the server machine the CLI uses the unix domain socket and runs as the admin user; --as builtin:user1 runs the command as that user instead. A remote CLI runs as the user who did openrun login, or as the user an API key belongs to. For the users of an app to log in from the CLI, add the app’s auth provider to the login mechanisms of the REST API surface:
[api.rest]
enable = true
auth = ["admin", "saml_okta"] # users of apps with --auth saml_okta can run openrun loginopenrun login --server https://openrun.example.com --auth saml_okta # browser login through the SAML provider
openrun action list # the actions of the apps saml_okta users can access--authselects the login when the server has more than one; without it the login page offers the choice.- The CLI keeps one login per server.
- An API key limited with
--scopesneedsapp:accessin its scopes to run actions.
MCP Tools
An app with actions serves them as MCP tools, for AI clients like Claude Code, Cursor and VS Code. No option and no change in the app code is required. The MCP endpoint is at /mcp under the app path; the form UI and the REST API stay as they are. The ops tools use case shows an agent session against a destructive action, with the confirmation prompt and the audit rows it leaves.
openrun app create --approve --auth builtin ./orders /orders
claude mcp add --transport http orders https://apps.example.com/orders/mcpThe endpoint
The endpoint is on by default:
--mcp=disable(oropenrun app update mcp disable /orders) turns all MCP off for the app: no endpoint, the app is left out of the endpoint for all apps, and the management action tools refuse it when called over MCP. The CLI, the REST API and the form UI are not affected.openrun app update mcp default /ordersgoes back to the default.--mcp=actionsis the same endpoint as an explicit setting; the JSON form changes the path or adds scopes (below). With an explicit setting an action cannot be defined at the endpoint path, and the app create fails when the server has no usable OAuth issuer origin.- Without a setting the endpoint never gets in the way: when the app has a route or an action at
/mcp, that route is served and the actions are not exposed there (set anotherpathto serve them). A container or proxy app, whose routes OpenRun cannot see, gives up its upstream path/mcpto the endpoint; use--mcp=disableor anotherpathwhen the upstream needs it. - The endpoint is served over HTTPS (and over plain HTTP on localhost, for development) on a server with an OAuth issuer origin, as for any MCP app.
The client connects with the OAuth flow described in MCP Apps:
- The user logs in with the app’s
auth, the token is bound to the app and RBACapp:accessapplies. - The app’s
scopesand per tool scope requirements (tools) are declared with the JSON form,--mcp='{"source":"actions","scopes":[...],"tools":{"cancel_order":"orders:write"}}'."path"moves the endpoint from the default/mcp. - API keys bound to the app (
openrun apikey create --resource app:/orders) work for clients which cannot run a browser flow.
How actions map to tools
Each action is one tool:
- Name: the action name used by the CLI (
cancel_order). The title is the action name and the description is the action description. - Input schema: the action’s params, with the type, the description, the app level value as the
default, the selector options as anenum(as thex-optionssuggestions for theCOMBOdisplay type, which accepts other values) and therequiredlist. Hidden params are left out. dry_run=trueruns the handler withdry_run=True, to validate the arguments without running the action. When the action has a param calleddry_runthe control is named_dry_run(with as many leading underscores as it takes to not be a param of the action); the tool description names it.- Suggest tool: an action with a suggest handler gets a second, read only tool named
<tool>_suggest(with a numeric suffix if another action already has that name; the description of the action’s tool names it). - Files: a tool call cannot carry a file. Params with the
FILEdisplay type are left out, and an action with a requiredFILEparam is not exposed as a tool. - Annotations: the side-effect hints of the action are its tool annotations; an action without hints has no annotations. The suggest tool and the run tools of async actions are marked read only.
Confirming destructive actions
An action declared destructive=True is confirmed by the user before it runs, when the client supports it (MCP protocol 2026-07-28 or later with the elicitation capability, which the current versions of the major clients have):
- The first call validates the arguments (as
dry_run=truewould; param errors are returned for correction instead) and answers with a confirmation prompt naming the action, the app, the arguments (password params hidden) and the status the validate pass reported. - The client retries the call with the user’s answer. The action runs only on an accepted answer.
- A declined call returns
statusdeclined by the user, no changes were made(not an error) and is recorded in the audit log as a failedmcp_executewithconfirm=declined.
A call with dry_run=true needs no confirmation.
What happens when the client cannot confirm (an older protocol, no form elicitation, a script calling the endpoint directly) is the destructive_confirm mode:
| Mode | Client can confirm | Client cannot confirm |
|---|---|---|
require (default) | confirmation prompt | refused with a tool error naming the action and the mode |
ask | confirmation prompt | runs at once |
skip | runs at once | runs at once |
The mode is set at three levels:
| Where | Effect |
|---|---|
[api.mcp] destructive_confirm | The server mode. A dynamic setting; it applies to the destructive management tools too |
action.destructive_confirm | The per app app config setting, openrun app update conf --promote 'action.destructive_confirm="skip"' /dev-tools, which overrides the server value for that app’s actions |
openrun apikey create --confirm skip | An API key which runs destructive tools without the prompt, for headless automation. It relaxes ask to skip for calls made with that key and never overrides require |
The audit event of every destructive call says how it was confirmed: confirm=accepted, declined, refused, unsupported (ran at once under ask), skipped or skipped_by_key. skip_destructive_confirm = true, the setting before modes existed, is the same as destructive_confirm = "skip".
Calling the endpoint by hand
- A refusal names what the request declared (its protocol version and elicitation capability).
- The
openrun_statustool of the endpoint for all apps reports the mode and whether the connection can confirm (can_confirm). - The legacy
initializehandshake is answered with protocol2025-11-25whatever the client asks for. In MCP 2026-07-28 the version and the client capabilities travel in the_metaof each request (io.modelcontextprotocol/protocolVersion,io.modelcontextprotocol/clientCapabilities), and that is what the confirmation needs.
The tool list
- The tools a user sees in the client are the actions their
permitallows. - The tool list is marked private to the caller’s client (
cacheScope) with a freshness hint (ttlMs) ofaction.mcp_list_ttl, an[app_config]setting (default3m, overridable per app withopenrun app update conf 'action.mcp_list_ttl="30s"' /orders): how long a client may use the listed tools before listing again. A dev app whose actions change often can set a short ttl. - The server does not push tool list changes. After a reload, promote or update which changes the actions, a client sees the new tools at its next listing, while every call is evaluated against the current actions regardless of the list the client holds (a removed tool fails, an added tool works).
Tool results
The result of a tool call has the structured result (status, report, values, param_errors) and a text block written for the model: the status line followed by a markdown table (the first 50 rows), the text lines, or JSON. Param errors are returned as a tool error listing param <name>: <message>, so that the model can correct the arguments and retry.
The files of IMAGE and DOWNLOAD results are returned inline, since an MCP client has no session with the app to fetch their url with. A single_access file is removed once it has been returned.
| Limit | Value |
|---|---|
| Text block | 64KB of values, with a note of how many values were left out |
| Structured values | 256KB (truncated is set) |
| Images | Returned as image content, up to 2MB each |
| Text files | Returned as embedded resources, as text, up to 256KB |
| Other files | Returned as embedded resources, as binary data, up to 1MB |
| Files inlined per result | Four. Larger or additional files, and urls outside the app, are returned as resource links |
| Streamed output | The last 64KB |
An action meant for AI clients should return a focused result rather than rely on the limits.
- Streaming: for an action which streams a command, the call returns when the command exits, with the output and the
exit_status; a non-zero exit is a tool error. Clients which pass a progress token receive the output as progress notifications while the command runs. - Audit: tool calls are recorded in the audit log under the user, with the operation
mcp_execute,mcp_validateormcp_suggest. - Async actions: the tool of an async action returns the
run_idandrun_statusof the started run. Its optionalwait_secondsargument (up to 60) waits for the run and returns the result as a sync tool would. An app with async actions has three more tools:
| Tool | Arguments | Effect |
|---|---|---|
get_run | run_id, wait_seconds | Returns a run with its result or the tail of its output |
list_runs | Lists the runs | |
cancel_run | Stops a run |
One endpoint for all apps
/_openrun/app_mcp is a single MCP endpoint whose tools are the actions of every app the user can run, each action its own tool. It is not served on a server which runs with security.unsafe_disable_rbac. The [api.app_mcp] settings are:
| Setting | Default | Meaning |
|---|---|---|
enable | true | [api.app_mcp] enable = false turns the endpoint off |
list_ttl | 3m | The freshness hint of the tool list |
max_tools | 300 | The list fails when it has more tools than [api.app_mcp] max_tools, asking for a narrower apps glob, rather than hide tools silently |
allowed_auth | empty | The logins the auth param may name; empty allows any configured one |
# Claude Code
claude mcp add --transport http apps https://openrun.example.com/_openrun/app_mcp
claude mcp add --transport http team "https://openrun.example.com/_openrun/app_mcp?apps=/team/**"
claude mcp add --transport http sso "https://openrun.example.com/_openrun/app_mcp?auth=google_openrun"
# Codex
codex mcp add apps --url https://openrun.example.com/_openrun/app_mcp
codex mcp add apps_builtin --url "https://openrun.example.com/_openrun/app_mcp?auth=builtin"A bare url connects without a login when the server’s default app auth is none (the default), and then lists only the actions of apps with auth none; add ?auth=<login> to log in and see your own apps. The tool list is empty until an app with actions is deployed. The server’s instructions, which the client receives on connecting, say who is connected and what the view is.
| URL param | Default | Meaning |
|---|---|---|
apps | all | App path glob selecting the apps of the view (/team/**, example.com:/**). A filter for the client’s convenience, not an access boundary |
auth | security.app_default_auth_type | The login: none, system, builtin, an [auth.*] entry name or saml_<name> |
stage | false | true lists and runs the staging version of each app |
- Who can run what is decided per app exactly as for
run_action: RBACapp:access, the app’s login (below) and the action’spermit. Apps and actions the user cannot use are not listed, and calling one answers as an unknown tool does. - One login per URL. An action runs only for a user who logged in the way the app’s users do. An
auth=builtinentry therefore lists the apps which use builtin auth, plus the apps with authnone(which accept any login). A user with apps on two logins adds two entries. The login is part of the token: a token for oneauthvalue is not accepted at another, nor at the management endpoint or an app’s own endpoint. auth=noneneeds no login. Requests run as theanonymoususer and list the apps with authnoneonly. That is what a bare URL does on a server whoseapp_default_auth_typeisnone(the default): add?auth=<login>to see your own apps too.- Tool names are
<app>__<action>. The app part is the app path with/as_(/team/ordersgivesteam_orders__cancel_order,/my-appgivesmy-app__ping). - Left out: apps with
--mcp=disable, and apps whose mcp setting has atoolsscope map (their tools need scopes only the app’s own endpoint can grant). - Same behavior as on the app’s own endpoint:
dry_run, the suggest tools, the confirmation of destructive actions, results with files, and the run tools of async actions (<app>__get_runand so on). openrun_statusis always listed: it reports the connected user and login, the view and the number of action tools in it, so an empty view can be told from a failed connection.- API keys:
openrun apikey create --user builtin:alice --resource app_mcp:builtin --scopes app:access(app_mcpalone is the default login; without--userthe key is the caller’s). Browser based clients are not supported, a request with anOriginheader is refused.
Tool naming rules
- An app whose path has other characters (
_,.), an app on another domain and the root app carry a short hash of their path instead of clashing with another app (team_orders--3fa2c41b__cancel). - A name depends on its app alone, it does not change when other apps are added.
- The app part is at most 24 characters and the action part 38, longer ones are cut and carry a hash.
Actions of all apps are also available through the generic list_actions, get_action, run_action and suggest_action tools of the management MCP surface, unless the app has --mcp=disable; list_action_runs, get_action_run and cancel_action_run manage the runs of async actions there, and run_action takes wait_seconds for them.
Multiple Actions
Multiple actions can be defined for an app. Each action should have a dedicated path. If there are multiple actions, a switcher dropdown is automatically added for the app. The order of entries in the dropdown is the same order as defined in the app.
See weather app code:demo for an example of using multiple actions in one app.
Actions for Spec Apps
An app built from a spec (for example --spec python-flask) has no app.star of its own: the spec’s app.star proxies every request to the container. Such an app adds actions with two optional files next to its code, without copying the spec’s app.star:
| File | Role |
|---|---|
actions.star | Defines the actions. It must set actions to a list of ace.action entries, and may set permissions to a list of ace.permission entries for the plugins the actions use. Both lists are appended to the app definition, after any entries in app.star. The file can load plugins and other .star files, and has the param module with the app’s param values |
action_params.star | Declares the params the actions present, with the same param(...) syntax as params.star. When this file exists, every action of the app shows exactly these params (minus the action’s hidden list) in the UI, the REST API, the CLI and the MCP tool schema, and args has exactly these params. The params.star params (for a spec app, the spec’s own params like port) are not shown. Without this file, every params.star param is an action param, as before |
The params of action_params.star are app params in every other way:
--param name=valueat create andopenrun param updateset the value the action presents as the default.- They are members of the
parammodule and are passed to the container environment like every param. - A name declared in both files is an error.
- A required action param without a default does not need a value at create time: it is supplied when the action runs, and a run or validate call without it is refused with a param error before the handler is called.
load("http.in", "http")
def list_orders(dry_run, args):
if dry_run:
return ace.result("Arguments are valid")
resp = http.get(ace.CONTAINER_URL + "/internal/orders", params={"status": args.status})
return ace.result("Orders", resp.value.json(), ace.TABLE)
actions = [ace.action("List Orders", "/orders", list_orders, description="Open orders from the app")]
permissions = [ace.permission("http.in", "get")]param("status", description="Order status", default="open")
param("options_status", type=LIST, default=["open", "closed", "all"])openrun app create --approve --spec python-flask --mcp=actions ./orders-app /orders
openrun action run /orders orders status=closed- The action’s handler reaches the container’s own APIs through the http plugin with
ace.CONTAINER_URL. - The action paths, the
/apipath of the actions REST API and the/mcpregion of--mcp=actionsare served by OpenRun; every other path is still proxied to the container. - Actions on such an app need a sub path, an action at
/cannot share the app root with the proxy.