Guide: Building Actions with a Coding Agent

The action-builder template is an MCP server with the tools and skills a coding agent, such as Claude Code, needs to build and test your tools, skills, agents, and MCP servers against your real data. The agent reads what exists, writes a candidate definition, checks it, and replays recorded work against it to show what the change would do. It never creates or publishes a definition: a person publishes what it validated.

Every request the agent makes is recorded as an execution of the server, with the reason the agent gave for it, like any other MCP server's.

What it installs

The template is one GraphQL operation that creates eleven ordinary actions, which you own and can edit from then on: seven tools, three skills, and the action-builder server that offers them.

Tool	What it does
`list_actions`	Lists your actions a page at a time, with each one's name, kind, status, and version.
`get_action`	Reads an action at its current or a retained version. Its `definition` is in the shape `createAction` takes, so the agent edits it and passes it back.
`validate_action`	Validates a candidate definition with `validateAction`, and evaluates its triggers against sample events. An invalid definition is an answer that says what is wrong, not an error. Nothing is stored.
`list_executions`	Lists executions of an action, of one of its sessions, in a status, or in an interval, newest first.
`get_execution`	Reads an execution: its outcome, what it was given and used, and its first calls, each with its output and the writes it would have made.
`get_lineage`	Walks what an execution caused, or what caused it.
`replay_execution`	Replays a recorded agent turn or MCP request against a candidate version or an unpublished definition. Its writes are always rolled back and recorded.

The server also lists the native tools program, invoke, and get_task, so the agent can preview a tool or agent it wrote, as a stored version or a draft, and read an agent's run.

The skills, write-starlark-tools, write-skills, and design-mcp-server, teach the agent the rules of each kind of definition: Starlark's entrypoint, calls, errors, and limits; skill names, descriptions, and examples; and an MCP server's sessions, stated intent, policies and annotations, programs, resources, and preview mode. The server also offers twisp://actions/{action_id} and twisp://executions/{execution_id} as resources, so you can attach an action or an execution to a conversation.

Permissions

Every call runs under your own permissions as well as the server's and the tool's, so give the people who use the server what its tools need:

Reading actions, executions, and sessions: SELECT on financial.Action.*, financial.ActionExecution.*, and financial.Session.*.
Validating a definition that references tools or skills: INVOKE on financial.Action.*, as creating it would.
Replaying: INVOKE on the replayed action and INSERT on financial.ActionExecution.*, and for an unpublished definition, UPDATE on financial.Action.* and INSERT and UPDATE on financial.Client.*, as publishing it would.
INVOKE on the action-builder server itself.

The read tools' policies allow only SELECT, so hosts can call them without asking you. validate_action and replay_execution need more, so hosts ask before each call.

What replays can reach

A replay the agent requests runs under everyone who requested it, you, the action-builder server, and replay_execution, as well as the principal of the work it replays. It can do nothing any of them could not, even though its writes are rolled back. The template grants the server and replay_execution no access to your business tables, so a replayed call that reads or writes them is denied, and its error names the server or the tool as the denying layer.

Decide which tables replays should reach, and add those grants to the action-builder server and to replay_execution. For example, to replay work that opens journals, allow INSERT and SELECT on financial.Journal.* in both. You also need that access yourself, as does the principal of the replayed work.

Likewise, get_execution lists only the written records that you, the server, and get_execution may all read, and counts the rest in write_set_unreadable. To see what a replay would write to a table, allow SELECT on it in the server and get_execution. Each tool's own policies still bind it, so a grant on the server reaches only the tools you grant too. Add only the tables you want the agent to see.

Replaying before you publish

The template's main use is testing a change against recorded traffic before anyone publishes it. For a change to a tool that an MCP server uses, the agent:

Lists the server's recent requests with list_executions.
Reads the server with get_action, and builds a candidate: for example, the same definition pinning the tool's new version.
Validates the candidate with validate_action.
Replays each chosen request against the candidate with replay_execution, choosing a new replay_id for each one and reusing it only to retry the same request.
Reads each replay with get_execution once it has run, and compares its calls' outputs, errors, and writes with the original request's.

It then gives you the validated definition and what the replays showed, and you publish it.

Pin the tool versions your MCP servers use, so that a new tool version reaches a server only when you update the server, after a replay shows what changes.

Preview mode and replays

Like every MCP server, action-builder starts in preview mode. Its reads and validations work fully in preview mode. A replay request, though, is itself a write, the replay's execution, so in preview mode it is recorded and discarded, and the replay never runs. Promote the server to LIVE when you want the agent to replay: none of its tools commits a business write, and a replay's writes are always rolled back.