# Visual feedback through MCP

For the full catalog → design → preview → revise → share workflow, install the [Rod Loom agent skill](install-skill.md): `npx skills add jaywolters/rodloom-skills --skill rodloom`. The skill includes client setup instructions and an HTTP fallback; it does not automatically configure this connection or enable vision.

Connect an image-capable agent to Rod Loom using **Streamable HTTP**:

- **Server URL:** `https://304heq9dze.execute-api.us-west-2.amazonaws.com/mcp`
- **Local URL:** `http://localhost:8000/mcp` after running `python server.py`
- **Authentication:** none; public, rate-limited, read-only rendering. Do not send sensitive data.
- **Tool:** `preview_design`

Add the URL as a remote MCP server in your agent client's settings, using its HTTP/Streamable HTTP transport (not legacy SSE). Configuration field names vary by client. The endpoint is on the dedicated API origin, **not** `rodloom.com/mcp`.

## Request visual feedback

Call `preview_design` with one argument, `design`, containing the **full design JSON** from the [quickstart](quickstart.md) or [example](example-design.json). `tools/list` publishes the full input schema, including paired spirals and thread metadata. The compact share-link payload is not accepted.

Conceptually:

```json
{
  "name": "preview_design",
  "arguments": {
    "design": { "version": 1, "name": "...", "threadSize": "D", "coverage": 0.25, "diameter": 15, "blank": "#263a40", "texture": true, "bands": [] }
  }
}
```

A successful tool result contains:

1. A **text content block** with validation details, dimensions, thread estimates and warnings.
2. A native **image content block** with `type: "image"`, `mimeType: "image/png"`, and base64 `data` for the 1200 × 720 rod-and-flat preview.
3. The same validation result in `structuredContent` for clients that support it.

The image is an actual MCP image block, not a download URL or a base64 string hidden inside text. The MCP client must forward image content to a vision-capable model. **A successful tool call alone does not prove the agent saw the image.** Text-only clients should continue to call the design unpreviewed, or save the PNG and open it with an image-viewing tool. Rod Loom does not generate an aesthetic score or textual visual critique; the requesting agent inspects the image.

Suggested agent workflow:

> Call preview_design. Inspect both images for color contrast, band balance, fade direction, and visible fine detail. Revise the design if necessary and render again. State whether you actually saw the image. Then generate an Open in Rod Loom link.

Colors, metallic/neon effects, and physical dimensions remain estimates. A rendered preview does not establish real-world fit or guide clearance. No design or image is persisted, and the tool does not open or replace a browser draft. Use [share links](share-links.md) separately to deliver the editable design.

## Transport and errors

The server implements stateless JSON responses over MCP Streamable HTTP, negotiating `2025-06-18` or `2025-03-26`. It has no session IDs, server-initiated requests, or persistent SSE streams. `GET` and `DELETE` return 405; accepted notifications return 202 with an empty body. Each request uses JSON-RPC 2.0 and `Content-Type: application/json`. Clients should send `Accept: application/json, text/event-stream` and the negotiated `MCP-Protocol-Version` header.

Invalid designs return a tool result with `isError: true` and explanatory text, with no image. Protocol errors use JSON-RPC errors. HTTP transport failures include 400 for malformed requests or unsupported protocol headers, 403 for rejected browser origins, 413 for oversized requests, and 415 for unsupported content types. Responses are `no-store`.

The JSON-RPC envelope is limited to 300,000 bytes; the nested design still has the 250,000-byte and 500-band limits. Rendering is bounded and offline: no submitted URLs are fetched, no code is executed, and no storage or AWS data-service permissions are needed. Browser origins are restricted to the Rod Loom HTTPS sites and localhost/loopback clients; non-browser clients may omit Origin. Existing API stage throttling applies.

## Verify interoperability from a checkout

With [uv](https://docs.astral.sh/uv/) installed, this optional smoke test installs the official MCP Python SDK into an isolated script environment; the deployed server itself has no added dependencies:

```sh
uv run scripts/smoke-mcp.py --output preview.png
# Local server instead:
uv run scripts/smoke-mcp.py --url http://localhost:8000/mcp --output preview.png
```

It initializes the connection, discovers the tool, validates the example, decodes the native image block, and checks that invalid designs produce a tool error rather than an image. Open `preview.png` to inspect the actual result.
