# Mockdraft MCP server

Mockdraft is a review and approval tool for visual prototypes of apps and websites, built as HTML. A design team uploads a prototype, its client marks and comments directly on the design, and approves each version when it is ready.

The MCP server is an optional integration. It lets an AI assistant that supports the Model Context Protocol work with a team's prototypes: find a prototype, read the client's feedback as instructions, get the HTML of the current version, publish the next version and close the marks it addresses.

- Endpoint: `https://mockdraft.dev/mcp`
- Transport: Streamable HTTP, stateless. Only `POST`; `GET` and `DELETE` answer `405`. Responses are JSON (no server-sent stream).
- Authentication: `Authorization: Bearer md_…`, a personal token.
- Language: tool names, parameters and responses are in Spanish. This page gives the English meaning of each one.

## Concepts

| Mockdraft term | Meaning |
| --- | --- |
| Equipo (team) | The design team or agency. Every token, prototype and client belongs to one team. |
| Cliente (client) | The company the prototype is for. It has contact people who review. |
| Prototipo (prototype) | An app or website being reviewed, such as «Sitio web 2027». It has numbered versions. |
| Versión (version) | One upload of the prototype: v1, v2, v3… Each one is a complete HTML document. |
| Marca (mark) | A numbered piece of feedback on a version, anchored to an element of the page. It can be open (`abierta`) or resolved (`resuelta`), and it can have replies. |
| Enlace de revisión (review link) | The private link the client opens to review. Clients do not need an account. |
| Aprobación (approval) | The client's sign-off on a version, with the full name they typed and the date. It cannot be edited or undone. |
| Acuerdo de confidencialidad (confidentiality agreement) | The team's agreement that each client reviewer accepts before seeing a prototype, if the team requires it. Each acceptance keeps a copy of the text. |

### Version states

The state of a version says what is being asked of the client (`pedido`, "the ask").

| State | Label | What the client can do |
| --- | --- | --- |
| `borrador` | Draft (Borrador) | Nothing. Only the team sees it. |
| `comentarios` | For comments (Para comentarios) | Mark and comment, but not approve yet. |
| `revision` | In review (En revisión) | Mark, comment and approve. |
| `cambios` | Changes requested (Cambios pedidos) | The client asked for changes. |
| `aprobada` | Approved (Aprobada) | Nothing else: an approved version no longer changes. |

A team can share a version for comments first and ask for approval later, on the same version, without uploading it again.

### Mark types

| Type | Meaning for whoever applies the feedback |
| --- | --- |
| Note (nota) | A comment pinned to an element. |
| `circular` (circle) | Keep this as it is. |
| `tachar` (strike) | Remove or change this. |
| `flecha` (arrow) | Move this, or relate it to another element. |
| `resaltar` (highlight) | Rewrite this text. |

Each mark points to an element by CSS selector and carries the client's comment, if any.

## Connect

### 1. Get a token

1. Sign in at https://mockdraft.dev/entrar. Access is by request; there is no public sign-up.
2. Go to Settings → Integrations (Ajustes → Integraciones) and create a token.
3. Copy it right away. It starts with `md_`, it is shown only once and Mockdraft stores only its hash.

The token acts as that person, inside their team. It stops working when it is revoked or when the person leaves the team. Each person can have up to 20 active tokens.

### 2. Configure the MCP client

Most clients with remote server support take a configuration like this one. Key names vary between clients (some use `transport` instead of `type`), so check the client's own documentation.

```json
{
  "mcpServers": {
    "mockdraft": {
      "type": "http",
      "url": "https://mockdraft.dev/mcp",
      "headers": { "Authorization": "Bearer md_YOUR_TOKEN" }
    }
  }
}
```

Clients that only run local (stdio) servers can connect through the `mcp-remote` bridge:

```json
{
  "mcpServers": {
    "mockdraft": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mockdraft.dev/mcp", "--header", "Authorization:${MOCKDRAFT_AUTH}"],
      "env": { "MOCKDRAFT_AUTH": "Bearer md_YOUR_TOKEN" }
    }
  }
}
```

Keep the token out of shared files and repositories. Use the client's secret storage or an environment variable when it has one.

### 3. Check the connection

```bash
curl -s https://mockdraft.dev/mcp \
  -H "Authorization: Bearer $MOCKDRAFT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A valid token returns the list of tools. An invalid or revoked one returns `401` with a JSON-RPC error.

## Tools

| Tool | What it does | Writes |
| --- | --- | --- |
| `listar_prototipos` | Lists the team's active prototypes with their current version, state and open marks. | No |
| `ver_prototipo` | Shows the versions of a prototype, their states, who approved and how many reviewers it has. | No |
| `crear_prototipo` | Creates a new prototype, and its client if it does not exist yet. | Yes |
| `publicar_version` | Publishes a new version from a complete HTML document. | Yes |
| `cambiar_pedido` | Changes what is asked of the client on the latest version: comments only, or approval too. | Yes |
| `obtener_feedback` | Returns the client's feedback on a version as a ready-to-apply prompt, plus the detail of each mark. | No |
| `obtener_html` | Returns the full HTML of a version. | No |
| `resolver_marcas` | Marks one or more marks of a version as resolved. | Yes |

### `listar_prototipos`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `estado` | `borrador` \| `comentarios` \| `revision` \| `cambios` \| `aprobada`, optional | Only prototypes whose current version is in this state. |
| `buscar` | string, optional | Text to search for in the prototype name. |

Use it to find a prototype's id (`prototipo_id`), which every other tool needs.

### `ver_prototipo`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `prototipo_id` | UUID | The prototype. |

### `crear_prototipo`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `nombre` | string, 1–120 characters | Prototype name. |
| `cliente` | string, optional | Client name. Created if it does not exist. |

The new prototype has no versions. Publish the first one with `publicar_version`.

### `publicar_version`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `prototipo_id` | UUID | The prototype. |
| `html` | string, up to 2,000,000 characters, optional | The complete HTML document of the version (`index.html`, with `<html>…</html>`). It can include JavaScript and animations. Required unless `archivos` includes `index.html`. |
| `archivos` | array, optional, up to 200 | The prototype's other files: scripts, styles, images, fonts, data. Each one is `{ "ruta": "js/app.js", "contenido": "…", "base64": false }`. Paths are relative to `index.html`, without a leading `/` or `..`. Binary files go in base64 with `"base64": true`. |
| `resumen` | string, optional, up to 500 characters | What changed, in one or two sentences for the client. |
| `resuelve` | array of integers, optional | Numbers of the marks of the previous version that this version addresses. They are marked resolved. |
| `pedido` | `revision` \| `comentarios` \| `borrador`, optional | What is asked of the client. `revision` (default): comment and approve. `comentarios`: comment only, no approval yet. `borrador`: the client does not see it. |

The old boolean `enviar_a_revision` still works (`false` means `borrador`), but `pedido` replaces it.

The response can include warnings (`Avisos`): root-absolute paths that were made relative, files the page uses that were not sent, resources loaded over `http://`, or file types that are not accepted. Read them and fix what they point out in the next version.

### `cambiar_pedido`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `prototipo_id` | UUID | The prototype. Always acts on its latest version. |
| `pedido` | `revision` \| `comentarios` | `revision`: ask the client for approval. `comentarios`: comments only. |

A draft can move to either one. An approved version no longer changes.

### `obtener_feedback`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `prototipo_id` | UUID | The prototype. |
| `version` | integer, optional | Version number. Latest by default. |
| `incluir_resueltas` | boolean, optional | Also include resolved marks, as context. |

### `obtener_html`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `prototipo_id` | UUID | The prototype. |
| `version` | integer, optional | Version number. Latest by default. |

### `resolver_marcas`

| Parameter | Type | Meaning |
| --- | --- | --- |
| `prototipo_id` | UUID | The prototype. |
| `numeros` | array of integers | Numbers of the marks to resolve. |
| `version` | integer, optional | Version number. Latest by default. |

## JavaScript and multi-file prototypes

Mockdraft does not sanitize or strip code: prototype JavaScript runs as is. Isolation is what keeps it safe.

What works:

- Inline scripts and scripts from CDNs over `https://`, ES modules, `fetch` of the prototype's own files, custom fonts, CSS and JS animations, canvas, video and audio.
- `localStorage`, `sessionStorage` and cookies, kept in memory for the length of the visit (the prototype runs in an isolated origin with no real storage).
- `alert`, `confirm` and `prompt`, and links that open in a new tab.
- Full-height sections (`100vh`), fixed headers and scroll-driven animations: the prototype is shown like in a browser, on a fixed-height screen with its own scroll. Desktop, tablet (820 × 1180) and mobile (390 × 844) widths.
- Several pages linked with relative links (`about.html`).

Rules:

- Use relative paths (`js/app.js`, `./img/logo.png`). Root-absolute paths (`/assets/app.js`) that point to uploaded files are rewritten in HTML, CSS and resource strings in JS, but not in JS imports. When building with Vite, set `base: './'`.
- Load external resources over `https://`.
- Forms cannot be submitted to a server, and the prototype cannot navigate the Mockdraft page. Handle forms with JavaScript (`preventDefault`).
- Marks attach to elements. Marks on elements that only exist after an interaction (an open menu or modal) show up when that element is on screen.

## Workflows

### Apply the client's feedback

1. `listar_prototipos` to find the prototype and its id.
2. `obtener_feedback` to read the open marks of the current version.
3. `obtener_html` to start from the HTML of that version.
4. Make the changes and call `publicar_version` with the full HTML, a short `resumen` and, in `resuelve`, the numbers of the marks you addressed.

Never invent mark numbers: use the ones `obtener_feedback` returns.

### Share for comments, then ask for approval

1. `publicar_version` with `pedido: "comentarios"`. The client can mark and comment, but sees no approve button.
2. When the version is ready, `cambiar_pedido` with `pedido: "revision"`. The client can now approve it, and the marks already left stay where they are.

### Start a new prototype

1. `crear_prototipo` with the name and the client.
2. `publicar_version` with the first HTML.
3. A person on the team shares the review link from the app (Share). The MCP server does not send links or messages to clients.

## Limits

- Each request: up to 3 MB.
- `html`: up to 2,000,000 characters. `html` plus `archivos`: up to 2,500,000 characters in total. Larger prototypes are uploaded as a `.zip` from the app (up to 50 MB).
- Everything is limited to the token's team. A prototype from another team answers as if it did not exist.
- Approval only happens on the client's review page. No tool can approve a version.

## Errors

Tool errors come back as a normal result with `isError: true` and a message in Spanish, for example «No existe un prototipo con ese id en tu equipo.» (no prototype with that id in your team). Transport errors use JSON-RPC: `401` for a missing, invalid or revoked token, `405` for anything other than `POST`, `413` for a request over 3 MB.

## More

- Mockdraft: https://mockdraft.dev/en
- Request access: https://mockdraft.dev/en#access
- Index for AI assistants: https://mockdraft.dev/llms.txt
