# Design Gallery

> The screen gallery and docs at design.gujo.ai, the design MCP and agent tokens. What is public and what needs a sign-in or a token.

[design.gujo.ai](https://design.gujo.ai) shows docs for design tokens, components and patterns, and a gallery of real app screens. People browse it, and agents read the same content through the design MCP and the agent API.

## What needs what

| Content | People (browser) | Agents |
|---|---|---|
| Landing, styles, tokens, components, pattern docs, MCP guide (`GET /mcp`) | Anyone | Anyone |
| Real screen gallery: explore, screens and screen code, products, brands, apps, search and search suggestions, research, agent pages, design images, code assets | Signed-in Gujo members | Token with the `read` role |
| Screen gallery JSON (`/api/v1/*`) | Signed-in Gujo members | Token with the `read` role |
| Design MCP (`POST /mcp`) | No | Token with the `read` role only |
| Reading docs (`/api/agent/manifest`, `docs/{slug}`, `docs/{slug}/versions`) | Signed-in Gujo members | Token with the `read` role |
| Writing and submitting docs | No | Token with the `write` role only |
| Reviewing docs | No | Token with the `review` role only |
| Remote collection (`/api/agent/collect/*`) | No | Token with the `collect` role only |

- Any member signed in with a Gujo account can see the real screen gallery. Someone who is not signed in gets a sign-in wall and returns to the original address after signing in. JSON and image requests get a 401 JSON response.
- Real screen grids embedded in the public doc pages appear only when you are signed in or present a token.
- The basis is judgment 2026-mr329.

## Agent tokens

Agents send a design agent token as `Authorization: Bearer <token>`. It is a different credential from an account API key.

| Role | What it allows |
|---|---|
| `read` | The design MCP, the real screen gallery and screen JSON, reading docs |
| `write` | Creating new doc versions and submitting them for review |
| `review` | The pending review list and recording reviews |
| `collect` | Opening remote collection runs, uploading captures and assets, submitting |

- Gujo staff issue and revoke tokens per agent. Members have no page to issue one themselves. [To verify] where an outside developer asks for a token.
- No token, an unknown token or a revoked token gets 401. A missing role gets 403.
- When a token is presented, the token decides even if there is a signed-in session. A bad token gets 401 even with a session.

## Design MCP

| Item | Value |
|---|---|
| Endpoint | `POST https://design.gujo.ai/mcp` |
| Authentication | Design agent token with the `read` role. Without one, 401 |
| Format | JSON-RPC 2.0. One JSON response per request, no SSE |
| Methods | `initialize`, `tools/list`, `tools/call`, `ping` |

Client configs are on the design MCP tab of [Connect MCP](mcp/index.md). Keep the token in the `GUJO_DESIGN_TOKEN` environment variable.

There are 13 read-only tools.

| Area | Tools |
|---|---|
| Products and brands | `gujo_search_products`, `gujo_get_brand` |
| Styles | `gujo_search_styles`, `gujo_get_style` |
| Screens | `gujo_search_screens`, `gujo_get_screen`, `gujo_get_screen_image`, `gujo_get_screen_code`, `gujo_get_code_asset`, `gujo_get_similar_screens` |
| Flows | `gujo_search_flows`, `gujo_get_flow` |
| Research | `gujo_research` |

The `gujo_get_*` tools take up to 10 items in one call.

Protocol details:

- `initialize` answers with the requested protocol version if the server knows it, and with the newest version it knows otherwise.
- An unknown `MCP-Protocol-Version` header value gets 400.
- Notifications and response messages get 202 with an empty body, non-JSON gets `-32700`, and batch requests get `-32600`.
- Unknown methods and tools are JSON-RPC errors. A tool that fails to run returns `result.isError`.
- `GET /mcp` is a guide page for people. Probing it with `Accept: text/event-stream` gets 405 with `Allow: POST`.

## Docs API

`https://design.gujo.ai/api/agent/*` reads and writes design docs version by version.

- Lists hold 24 items per page in the shape `{data: [...], meta: {...}}`.
- Creating a version on a stale `base_version` gets 409. Submitting a draft another agent wrote gets 403.
- Only the agent that opened a remote collection run can continue it, and opening a run while another one is collecting gets 409. Captures and assets are uploaded as `multipart/form-data`.

Every path and input field is in the `design` group of the [API reference](api-reference.md).