proposal

Build with an AI agent

This is a proposal. A design under discussion, not yet shipped. It may change or be dropped. It describes where Akuma is headed and why: connecting your mock server to a coding agent over MCP, so the backend takes shape as the agent builds the app.

The thesis

Akuma's whole reason to exist is "stop waiting for the backend." With an AI agent in the loop, that becomes literal: the agent builds your frontend, and the backend follows it, one step at a time. Instead of hand-writing fixtures or guessing at response shapes, the agent reaches into the running mock and evolves it to match what the UI actually needs.

We want Akuma to be the backend your coding agent owns and reshapes live, not one more static mock you configure by hand.

How it works today

An agent can already edit your akuma.yml as a file. But it does so blind: it cannot see whether a change is valid until something breaks, it cannot see the real seeded data, and it has no idea which requests your app actually made. So it guesses, and you correct it.

The proposal: akuma mcp

Run a small server that exposes the running mock to your agent over MCP. Point your agent at it once:

json 
{
  "mcpServers": {
    "akuma": { "command": "akuma", "args": ["mcp"] }
  }
}

Now the agent has tools that do what a file edit cannot:

  • Read the API. List endpoints, inspect models and relationships, and pull a real sample response from the running server.
  • Change it, validated. Add a model or endpoint and Akuma checks it the same way the engine does, handing back valid or the exact error so the agent self-corrects. The write lands in akuma.yml and the server hot-reloads, so it is live a second later.
  • See what the app asked for. The requests your frontend actually made, including the ones that did not match anything yet.

The feedback loop

That last tool is the point. Your app calls GET /cart, which does not exist yet. Akuma records it as unmatched. The agent sees it, adds the endpoint, and the next request succeeds. The application drives the backend into existence, instead of the other way around.

It is a real loop: build the UI, the UI reveals what the API needs, the agent fills the gap, repeat. Nobody hand-writes a fixture.

It stays yours

Every change the agent makes is a write to akuma.yml, so it shows up as a normal git diff you can read, keep, or revert. The config file stays the single source of truth; the agent is just a fast, validated editor of it. Writes are local only and never touch a deployed server, which keeps the same boundary akuma deploy already draws.

Open questions

  • Does the agent connect to a server it auto-detects, or do you point it at one?
  • How much of the running data should it be able to read and seed directly?
  • What is the right ergonomics for editing matched responses through a tool call?
  • Read-only introspection of a deployed server: useful, or out of scope?

For what is actually built today, see Getting started and Endpoints.