# Shyne agent guide

> Agent instruction: connect to Shyne, read the MCP resource `shyne://guide/canvas-authoring`, and use `tools/list` as the live source of tool names and schemas. This page covers connection and conduct; the resource is the authoritative authoring contract.

Shyne is a collaborative design workspace where people and AI work on the same editable artifacts.

## Connect

```text
https://mcp.shyne.ai/mcp
```

The endpoint uses Streamable HTTP and OAuth. For example:

```sh
claude mcp add --transport http shyne https://mcp.shyne.ai/mcp --scope user
```

After adding the server, open `/mcp` and complete authentication.

## Mental model

- A Task is a durable agent conversation in the workspace. It may be filed in one Project.
- A Project is a cloud identity, access, collaboration, and context boundary. It owns Files and
  Canvases; a desktop folder is only a managed, sync-on-use working copy of its Files.
- A Canvas is one durable realtime visual workspace. It can contain loose Frames, Groups, and Nodes, plus several independently addressable Sequences.
- A Sequence is an ordered or timed set of Frames. Presentations, documents, carousels, and videos are profiles and outputs, not separate storage types.
- Frame is the bounded render/export region. Node is editable content. Group is a Node container.

## Orient before editing

1. Call `projects_list` and select the exact Project.
2. Call `canvases_list`, then select the exact Canvas. Pass `projectId` and `canvasId` on Canvas-bound calls. Canvas omission is valid only when the Project has exactly one Canvas.
3. Read `shyne://guide/canvas-authoring` once per working session.
4. Call `canvases_read` before changing anything.

## Working loop

- Make structured edits with `frames_apply` and `nodes_apply`; use `sequences_*` for membership, order, and Sequence settings.
- Use `canvases_import` to create structured content from HTML or SVG. Use `frames_replace_from_html` only when the user explicitly accepts destructive replacement.
- Use `canvases_preview` after visual changes and inspect the result before reporting completion.
- Re-read with `canvases_read` after structural changes.
- Use `projects_open` when the finished work should appear in the first-party app.

## Media, timeline, and export

Use `stock_search` for real-world assets, the `media_generate_*` tools for generation, and `files_list`/`files_upload` for Project files.

A timed Sequence owns video-wide playback settings. Inspect and edit clips with `timeline_get` and the `timeline_*` mutation tools. Preview exact moments with `canvases_preview`. Create durable outputs with `exports_create`; poll asynchronous video work with `exports_get`.

## Capabilities

The default hosted surface includes core authoring, media, and timeline tools. Read `shyne://capabilities` to discover optional packs. Clients may request supported packs with the MCP URL query parameter `packs`, for example `?packs=publishing,connections`.

Tool names use ASCII letters, digits, hyphens, and underscores. Shyne's public names use underscores, such as `sequences_get`.

## Boundaries

- Every call is authorized against the signed-in user and its declared scopes.
- Destructive operations are separately identified and scoped.
- Provider credentials are never returned to agents.
- The local desktop endpoint is loopback-only and acts as the user signed into the desktop app.

## Bootstrap prompt

```text
You have access to Shyne through the MCP server named "shyne".

Before changing anything, call projects_list and canvases_list, select the exact Project and Canvas, read the MCP resource shyne://guide/canvas-authoring, and call canvases_read. Pass projectId and canvasId explicitly on Canvas-bound calls.

Preserve everything the request does not ask you to change. Use frames_apply and nodes_apply for structured edits, sequences_* for ordered or timed Frame sets, and canvases_preview to inspect visual results. Use exports_create for durable outputs.

Now complete this task in Shyne: [DESCRIBE THE OUTCOME, AUDIENCE, FORMAT, CONTENT, AND ANY BRAND CONSTRAINTS].
```
