# Building Actions with a Coding Agent

Install the action-builder MCP server template so a coding agent can read your actions and executions, validate the definitions it writes, and replay recorded work against them before a person publishes them.

The **action-builder** template is an [MCP server](https://www.twisp.com/docs/reference/actions/mcp.md) 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`](https://www.twisp.com/docs/reference/actions/actions.md#validation), 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](https://www.twisp.com/docs/reference/actions/mcp.md#replay) 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`](https://www.twisp.com/docs/reference/actions/mcp.md#programs), [`invoke`](https://www.twisp.com/docs/reference/actions/mcp.md#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:

1. Lists the server's recent requests with `list_executions`.
2. Reads the server with `get_action`, and builds a candidate: for example, the same definition pinning the tool's new version.
3. Validates the candidate with `validate_action`.
4. 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.
5. 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](https://www.twisp.com/docs/reference/actions/mcp.md#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.