# Maketa MCP Server

Give your AI assistant hands on real app-screen mockups.

**Maketa** is a browser-based screen builder for mobile apps and landing pages. Every
board is stored as an explicit JSON scene model (`maketa.board.v2`) — so an assistant
does not guess pixels from a screenshot, it reads and writes the same structured objects
a human edits in the editor.

- Website: https://maketa.pro
- Docs for agents: https://maketa.pro/llms.txt · OpenAPI 3.1: https://maketa.pro/openapi.json
- Remote MCP endpoint: `https://maketa.pro/maketa/api/mcp` (Streamable HTTP)

---

## Quick start — remote server (recommended, nothing to install)

### Claude Code

```bash
claude mcp add --transport http maketa https://maketa.pro/maketa/api/mcp
```

You will be asked to sign in with your Maketa account (OAuth 2.1, PKCE, dynamic client
registration — no API key to copy around).

### Any MCP client that supports remote servers

```json
{
  "mcpServers": {
    "maketa": {
      "type": "http",
      "url": "https://maketa.pro/maketa/api/mcp"
    }
  }
}
```

### Headless (CI, autonomous agents — no browser, no human)

Send a bearer token instead of doing OAuth:

```bash
# 1. An agent can issue itself a 14-day sandbox key, no account needed:
curl -X POST https://maketa.pro/maketa/api/agent/register \
  -H 'content-type: application/json' \
  -d '{"name":"my-agent","purpose":"prototype screens"}'
# → {"key":"mk_sb_…","expiresAt":…,"quotas":{"boards":5,"savesPerDay":200}}

# 2. Call MCP with it:
curl -X POST https://maketa.pro/maketa/api/mcp \
  -H "Authorization: Bearer mk_sb_…" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A **project key** (`mk_pk_…`, issued by a board owner) works the same way and is
permanent, scoped to one board — that is what CI uses to push screens from code.

| Credential | Scope | Lifetime |
|---|---|---|
| OAuth access token | all boards of the signed-in user | 1 hour (refresh token: 30 days) |
| `mk_pk_…` project key | one board | until revoked |
| `mk_sb_…` sandbox key | sandbox boards created with that key | 14 days, 5 boards, 200 saves/day |

## Quick start — local stdio server

```json
{
  "mcpServers": {
    "maketa": {
      "command": "npx",
      "args": ["-y", "maketa-mcp"],
      "env": {
        "MAKETA_BOARD": "<board id>",
        "MAKETA_EDIT": "<edit token>",
        "MAKETA_PKEY": "mk_pk_…"
      }
    }
  }
}
```

`MAKETA_BOARD` and `MAKETA_EDIT` come from the editor's **Share** dialog: the edit link
is `https://maketa.pro/app/?b=<BOARD>&e=<EDIT>`.

---

## Tools

| Tool | What it does |
|---|---|
| `maketa_list_boards` | List the boards (mockup files) the caller can access. |
| `maketa_list_screens` | List screens of a board with a summary: name, device, size, node count, branches. |
| `maketa_get_screen` | Read one screen: slots and the node tree. |
| `maketa_get_tree` | Read the subtree of one node — cheaper than the whole screen on large boards. |
| `maketa_create_screen` | Create a screen (device preset, size, background). |
| `maketa_add_node` | Add a node to a slot or inside another node. |
| `maketa_update_node` | Patch a node: size, layout, look, content, action. |
| `maketa_move_node` | Move a node to another parent or position in the tree. |
| `maketa_remove_node` | Delete a node with its subtree. |
| `maketa_branch_screen` | Branch a screen into an editable copy — the only way to redesign a screen that came from code. |
| `maketa_push_code_screen` | Upsert a screen from source code by a stable key; every push is a new version ("commit from code"). |
| `maketa_list_branches` | List the branches of a screen. |
| `maketa_get_parent` | Get the parent screen of a branch (navigate back to the code original). |

## The scene model (`maketa.board.v2`)

A screen is a **tree of nodes**, not a list of shapes — the same model a human edits in
the browser. Children have no coordinates: position is decided by the parent, exactly
like on the three native platforms ("constraints down, sizes up, parent positions").

```
screen
 ├─ slots.top      one node    — header, kept while scrolling
 ├─ slots.body     one node    — the scrolling content
 ├─ slots.bottom   one node    — tab bar
 └─ slots.over[]   nodes drawn above everything (sheets, dialogs)
```

Node: `{ id, type, name, children[], w, h, layout, look, content, action }`.

| Field | Meaning |
|---|---|
| `type` | `screen \| stack \| item \| text \| image \| button \| input \| choice \| tabs` — nine types; cards, grids and lists are *presets* built from `stack`, not separate types |
| `w` / `h` | `"hug"` (fit content), `"fill"` (take the parent's space) or a number |
| `layout` | `dir` `down\|right\|over\|wrap`, `pad`, `gap`, `main`, `cross`, `scroll`, `cols`, `visible` (how many cards fit in a row — that is how their width is set) |
| `look` | background, border, radius, shadow, image fill |
| `content` | text, placeholder, items, `lines`, `ratio`, `repeat: N` (one sample instead of N copies) |
| `action` | what a tap does: open a screen (`push\|modal\|dialog\|replace`) or reveal a block on the same screen |

Board-level `shared` holds the header and tab bar shown on every screen; a screen can opt
out with `noShared`. Layout is computed by the same engine in the browser, in Node and on
the server, so what the assistant builds is what the human sees.

## Code ↔ design branching

Screens pushed from source code (`kind: "code"`) are **locked**. An assistant that wants
to redesign one calls `maketa_branch_screen` and edits the branch — a proposal that lives
next to the original. When the code moves on and a new version is pushed, existing
branches are flagged `baseStale`, so nobody silently reviews an outdated design.

## Example prompts

- "Show me the screens of my Maketa board and describe the checkout one."
- "Add a primary button at the bottom of the login screen and link it to the home screen."
- "Branch the profile screen that came from code and propose a cleaner layout."

## Privacy & security

The server sees only your boards (screen objects), your account e-mail and board ids.
An OAuth token grants read/write to that user's boards only; a project key is limited to
one board; a sandbox key is limited to its own sandbox boards, expires in 14 days and
cannot use paid AI features or billing. Access can be revoked from the Maketa account
page, project keys via `POST /project/key/revoke`.

- Privacy policy: https://maketa.pro/privacy/
- Terms: https://maketa.pro/oferta/

## License / contact

Maketa is free to use. The MCP server is made by [demda.pro](https://demda.pro), a custom
software development studio. Questions: support@maketa.pro