# Twisp for AI Agents

Start Twisp on your machine, connect your agent with one URL, and it can design, build, verify, and automate a ledger, with every call it makes recorded.

An AI agent can do real accounting work in Twisp from its first minute: design a chart of accounts for a business, encode its money movements as tran codes, post and verify them, and then build the tools, agents, and MCP servers that automate it. Getting there takes two steps.

## 1. Start Twisp

```sh
docker run -p 3000:3000 -p 8080:8080 -p 8081:8081 public.ecr.aws/twisp/local:latest
```

The [local environment](https://www.twisp.com/docs/infrastructure/local-environment.md) needs no sign-in. When it starts, it prints the URL of its MCP server:

```
MCP server: http://localhost:8080/mcp/v1/000000000000/default
```

## 2. Connect your agent

Add that URL to your agent as an MCP server. In Claude Code:

```sh
claude mcp add --transport http twisp http://localhost:8080/mcp/v1/000000000000/default
```

Or check it into a project's `.mcp.json`, so every agent working in the project has it:

```json
{
  "mcpServers": {
    "twisp": { "type": "http", "url": "http://localhost:8080/mcp/v1/000000000000/default" }
  }
}
```

In VS Code, add the same entry under `servers` in `.vscode/mcp.json`. Then ask for something real:

> We're launching a peer-to-peer wallet. Customers fund it by ACH, send money to each other, and withdraw. Design the ledger in Twisp, post a day of realistic activity, and prove the books balance.

## What your agent gets

The `default` server is the whole of Twisp, offered to an agent:

| Tool            | What it does                                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `graphql`       | Runs any query or mutation of the [GraphQL API](https://www.twisp.com/docs/reference/api.md). The schema documents itself, so the agent learns it by introspection.                     |
| `cel`           | Evaluates a [CEL](https://www.twisp.com/docs/reference/cel.md) expression, so the agent can try a tran code's expressions before it creates the tran code.                               |
| `program`       | Runs a Starlark program over these tools in one transaction. With `commit: false` it previews every row it would write, so a whole design can be checked first. |
| `invoke`        | [Runs](https://www.twisp.com/docs/reference/actions/mcp.md#invoke) a tool or agent the agent built. With `commit: false`, the default, it previews a stored version or a draft and commits nothing, showing the output or error, the calls, and the rows it would write; with `commit: true` it runs the published version for real. |
| `get_task`      | Reads an agent's run that `invoke` started, until it finishes.                                                                                                                                 |
| `cancel_task`   | Cancels an agent's run that `invoke` started.                                                                                                                                                  |
| `audit`         | Reads back what this session did: each request, with its intent and status. See [the default server](https://www.twisp.com/docs/reference/actions/mcp.md#the-default-server).                                               |

And skills, which carry what an experienced Twisp engineer knows. The agent loads each one when the work calls for it:

| Skill               | When                                                                                                                  |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `basics`      | Before its first call: the ledger model and the API conventions that matter.                                          |
| `design`     | Before designing accounts and tran codes: following the money, normal balances, layers, limits, and proven patterns. |
| `verify`     | Before calling a ledger correct: the trial balance, expected balances, reconciliation, and testing the rules.         |
| `actions`     | Before building tools and automations that run on ledger changes.                                                     |
| `agents`      | Before building agents that run inside Twisp.                                                                         |
| `mcp` | Before offering tools to other agents through an MCP server of its own.                                               |

## Every call is recorded

Each request your agent makes is an [execution](https://www.twisp.com/docs/reference/actions/executions.md) of the `default` server, recorded with the reason the agent gave for it: every tool requires an `intent`. So the whole design and build is an audit trail, which you can read back:

```graphql
query WhatMyAgentDid($server: UUID!) {
  actions {
    executions(where: { actionId: $server }, first: 50) {
      nodes {
        created
        status
        mcpRequest { method name intent }
      }
    }
  }
}
```

Find the server's `actionId` with `actions { actions(first: 50) { nodes { actionId definition { name } } } }`.

## Make it yours

The `default` server is made of ordinary [actions](https://www.twisp.com/docs/reference/actions.md): the server, its tools, and its skills are yours to change. Add your own tools and skills to it, write skills about your business, or build narrower servers for other teams and agents. In the local environment the server runs `LIVE`, so its writes commit; a server you deploy for others starts in [preview mode](https://www.twisp.com/docs/reference/actions/mcp.md#preview-mode) until you promote it. To connect hosts to servers in your Twisp cloud environment, see [Connecting MCP hosts](https://www.twisp.com/docs/guides/mcp-hosts.md).

## Without MCP

An agent that cannot use MCP can still work with Twisp: the GraphQL API is at `http://localhost:8080/financial/v1/graphql`, and [`/llms.txt`](https://www.twisp.com/docs/llms.txt) indexes these docs for agents.