# MCP server

> A remote Model Context Protocol server, so any MCP-capable agent can read and write Sunny projects, rooms, catalog, and quotes over the network.

A remote [Model Context Protocol](https://modelcontextprotocol.io/) server, so any MCP-capable agent can read and write Sunny projects, rooms, catalog, and quotes over the network.

## Endpoint

`POST https://agents.sunnysdk.com/mcp` — stateless [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http): one JSON-RPC request per call, no session id. Responses come back as plain JSON, not an SSE stream. `GET` and `DELETE` return 405.

Required headers

```http
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <access token>
```

**No tool spends model tokens.** There is no arrange, plan-floor, or AI preview render over MCP. Every tool is a read, a deterministic render, or a write that changes stored data.

## Connecting

1. **Find the authorization server.** `GET /.well-known/oauth-protected-resource` on `agents.sunnysdk.com` returns [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) metadata naming the authorization server and its scopes. A 401 from `/mcp` carries the same URL in a `WWW-Authenticate` header, so a compliant client can find it with no out-of-band config.

   GET https\://agents.sunnysdk.com/.well-known/oauth-protected-resource

   ```json
   {
     "resource": "https://agents.sunnysdk.com/mcp",
     "authorization_servers": [
       "https://auth.sunnysdk.com/api/auth"
     ],
     "bearer_methods_supported": [
       "header"
     ],
     "scopes_supported": [
       "openid",
       "profile",
       "email",
       "offline_access",
       "projects:read",
       "projects:write",
       "quotes:read",
       "quotes:write",
       "quote_costs:read",
       "orders:write",
       "arrange",
       "workflows:run",
       "workflows:read",
       "catalog:read",
       "catalog:write",
       "favorites:read",
       "favorites:write",
       "docs:read",
       "embeds:write",
       "embeds:read",
       "webhooks:manage",
       "org:admin",
       "audit:read",
       "inbox:read",
       "inbox:write"
     ]
   }
   ```

   A server card for pre-connection discovery is also served at `/.well-known/mcp/server-card.json`.

2. **Register a client.** Preferred: host a JSON [Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/02/) at a public HTTPS URL (MCP 2026-07-28 profile — the document needs `client_name` and `redirect_uris`) and use that URL as your `client_id` directly; no registration call needed. See [Registering a client](/docs/oauth#registering-a-client) for the document shape. [RFC 7591 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) at `POST https://auth.sunnysdk.com/api/auth/oauth2/register` still works as a fallback for a client that can’t serve a metadata document.

3. **Authorize.** OAuth 2.1 authorization code with PKCE, with `resource=https://agents.sunnysdk.com/mcp`. The user consents on Sunny every time; a grant is never silently re-issued. Ask for only the scopes you need — see [OAuth & scopes](/docs/oauth) for what each one grants.

4. **Call the endpoint.** Every request carries the Bearer token. The MCP server accepts OAuth Bearer tokens only — no API keys, no cookies. A missing, invalid, or expired token always gets a 401.

## Tools

Scope is checked on every tool call, not once at connection time. Everything is scoped to the user’s active workspace: an id belonging to another workspace reads as “Not found”, so another workspace’s data and a typo are indistinguishable by design.

Clients that support MCP Apps render some results as interactive cards (catalog search, a product card, a project, a live room). Every tool also returns a text result for clients that don’t.

### Projects and rooms

| Tool                 | Scope            | What it does                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_projects`      | `projects:read`  | Projects visible to the user’s active workspace, as a short summary of each (floors and room counts).                                                                                                                                                                                                                                            |
| `get_project`        | `projects:read`  | One project by id, with its floors and spaces.                                                                                                                                                                                                                                                                                                   |
| `create_project`     | `projects:write` | Create a project, optionally with its first floor. Also needs `projects:read`.                                                                                                                                                                                                                                                                   |
| `update_project`     | `projects:write` | Rename a project or change its status or address. Also needs `projects:read`.                                                                                                                                                                                                                                                                    |
| `archive_project`    | `projects:write` | Archive a project: it leaves the project list but keeps its floors, rooms and history. Also needs `projects:read`.                                                                                                                                                                                                                               |
| `restore_project`    | `projects:write` | Bring an archived project back to the project list. Also needs `projects:read`.                                                                                                                                                                                                                                                                  |
| `share_link`         | `projects:write` | A view link to a project, floor or room that anyone can open read-only. A project link can be made for one client and emailed to up to 10 addresses. Also needs `projects:read`.                                                                                                                                                                 |
| `invite_to_project`  | `projects:write` | Invite up to 10 people by email to view a project in Sunny. Also needs `projects:read`.                                                                                                                                                                                                                                                          |
| `get_floor`          | `projects:read`  | One floor by id, with its rooms and a floor check (rooms overlapping, off the plate, on the core).                                                                                                                                                                                                                                               |
| `get_space`          | `projects:read`  | One space (room) by id with its openings and finishes, its project and floor by id and name, outlines of the other rooms on that floor, and its arrangement history, newest first. With `projects:write`, also the room as an open studio tab has it right now (`liveRoom`).                                                                     |
| `create_space`       | `projects:write` | Create a room with a name and size in meters, on a floor or in a project, optionally at a spot (`x`, `y`). Pass `rooms` to create several at once. Returns its id and studio link, and turns on live editing for the project unless you pass `liveEditing: false`. Also needs `projects:read`.                                                   |
| `move_room`          | `projects:write` | Move and/or resize one room on its floor in one call. Refused if it would leave the room overlapping another, off the plate or on the core. Also needs `projects:read`.                                                                                                                                                                          |
| `edit_rooms`         | `projects:write` | Move, resize and rename several rooms on one floor, all or nothing (rooms can swap places). Also needs `projects:read`.                                                                                                                                                                                                                          |
| `edit_room_shell`    | `projects:write` | Add, change or remove one room’s doors and windows, and set its wall height and wall and floor finishes, including one wall’s own paint for a feature wall. Paints take a preset name (Oak, Walnut, White, …) or a hex. Reports the room’s layout check, and any opening saved narrower than asked. Also needs `projects:read`.                  |
| `reshape_room`       | `projects:write` | Make a room a rectangle, an L (one corner cut out) or a U (a notch in one wall). Refused if the notch doesn’t fit or the new outline would overlap another room or leave the plate. Reports the room’s layout check. Also needs `projects:read`.                                                                                                 |
| `update_floor`       | `projects:write` | Change a floor’s name, plate size, budget or target headcount. A smaller plate that would leave a room off it is refused, with the smallest plate that fits. Also needs `projects:read`.                                                                                                                                                         |
| `create_floor`       | `projects:write` | Add a floor to a project, optionally with a plate size. Also needs `projects:read`.                                                                                                                                                                                                                                                              |
| `move_room_to_floor` | `projects:write` | Move a room to another floor of the same project, with its pieces and history, into a clear spot. Also needs `projects:read`.                                                                                                                                                                                                                    |
| `archive_room`       | `projects:write` | Archive a room: it leaves its floor but keeps its pieces and history. Also needs `projects:read`.                                                                                                                                                                                                                                                |
| `restore_room`       | `projects:write` | Bring an archived room back to its floor. Also needs `projects:read`.                                                                                                                                                                                                                                                                            |
| `export_file`        | `projects:read`  | A room’s or floor’s file for another tool, as a download link: the plan for CAD (DXF, in mm, inches or metres) or the 3D model (GLB). Drawn from what was last saved.                                                                                                                                                                            |
| `export_layout`      | `projects:read`  | A space’s current arrangement as a [sunny-layout](/docs/layout-interchange) document.                                                                                                                                                                                                                                                            |
| `import_layout`      | `projects:write` | Import a sunny-layout document into a space as a new saved version. Unknown catalog ids are dropped and reported per item.                                                                                                                                                                                                                       |
| `render_plan`        | `projects:read`  | A top-down plan as a PNG plus a text legend, for the agent to check its work: one space, every room on a floor, or a sunny-layout document rendered without saving it. It opens no card; `show_room` is the person’s view.                                                                                                                       |
| `render_view`        | `projects:read`  | A 3D view of a space as an image, captured by the studio tab that has the room open for live editing (needs `projects:write` too). With no such tab it returns an error; use `render_plan` instead.                                                                                                                                              |
| `set_studio_view`    | `projects:write` | Switch the person’s open studio tab (live editing on) to another room on its floor or to the floor overview, and set its view (`3d` or `top`) and camera. Refuses over unsaved edits, and names the floor when the tab is on another one.                                                                                                        |
| `show_room`          | `projects:read`  | A live card for one room, in 2D or 3D, that follows edits as they happen. Call it once before editing. Where the app allows, expand it to full screen to keep it in view. With only `projects:read` it shows the room as last saved.                                                                                                             |
| `place_item`         | `projects:write` | Live edit: add a catalog piece at a position in meters, or several at once with `items`.                                                                                                                                                                                                                                                         |
| `move_item`          | `projects:write` | Live edit: move or turn a piece by id. Only the fields you pass change.                                                                                                                                                                                                                                                                          |
| `remove_item`        | `projects:write` | Live edit: remove a piece. The person can undo it from the studio.                                                                                                                                                                                                                                                                               |
| `attach_item`        | `projects:write` | Live edit: clip a part onto a host piece (an overhead onto a wall panel), or detach it with `hostId: null`.                                                                                                                                                                                                                                      |
| `configure_item`     | `projects:write` | Live edit: change a piece’s settings: switch a TV or lamp on or off, open or shut a lid, or set its finish, size preset or per-slot material. `null` resets a setting.                                                                                                                                                                           |
| `edit_items`         | `projects:write` | Live edit: apply a batch of moves, removals and attaches to pieces already in the room as one all-or-nothing edit. The person can undo it from the studio.                                                                                                                                                                                       |
| `place_typical`      | `projects:write` | Live edit: place a manufacturer typical (an id from `search_typicals`) as a single group, every part assembled and finished as a set, or several at once with `items`. One asked to stand in a door’s way is moved just clear when there is room nearby, and the reply says where. Returns the group id, its seat slots and any layout problems. |
| `fill_slot`          | `projects:write` | Live edit: put a chosen chair in one of a placed typical’s seat slots, where it takes the old chair’s place, or clear the slot with `catalogId: null`.                                                                                                                                                                                           |

**Live edits** (`place_item`, `move_item`, `remove_item`, `attach_item`, `configure_item`, `edit_items`, `place_typical`, `fill_slot`) change a room while it is open in the Sunny studio with live editing turned on (**Connect AI** in the studio). If no studio tab has the room connected, the call returns `isError: true` saying so, and nothing changes. Take the room id from `get_project` or `get_floor`, and piece ids from `get_space`’s `liveRoom`. When the room is open this way, `get_space`, `render_plan`, and `render_view` also see its unsaved edits.

To start a new room for live editing, call `create_space`. By default it turns on **live editing for all rooms in the project**, a project setting that connects each room when the person opens it in the studio, so they don’t need to click Connect AI in every room. Give the person the returned `studioUrl`; once the room is open, the live edits work on it. Until then, `import_layout` saves a layout to the room. The setting only changes when a room connects, not who can connect: the person still needs edit access to the project, and they can turn it off from Connect AI.

Before calling `configure_item`, call `get_space` with `options: true` to see which finishes and size presets each piece offers. `liveRoom.options` lists them once per catalog id, and only for items with more than one choice, for example `{ "rug": { "finish": ["Terracotta", "Sand", "Sage", "Indigo"], "size": ["Runner", "4×6′", …] } }`. It’s left out by default to keep the room compact. A piece’s `catalogId` in `liveRoom.items` is the key.

### Catalog

| Tool                   | Scope          | What it does                                                                                                                                                                                                                                                          |
| ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_catalog`       | `catalog:read` | Free-text and category search over the catalog. Returns text for the agent and shows the person nothing.                                                                                                                                                              |
| `search_typicals`      | `catalog:read` | The manufacturer typicals (ready-made workstations and assemblies) you can place with `place_typical`, by family or free text. Each lists its footprint, seats and the chairs it ships with, and a from-price; `detail: true` adds each seat slot and the part count. |
| `inspect_catalog_item` | `catalog:read` | Full detail for one catalog id: footprint, finishes, sizes, and configuration options.                                                                                                                                                                                |
| `show_catalog_item`    | `catalog:read` | One catalog item as an interactive product card (3D view, finishes, sizes, configured price).                                                                                                                                                                         |
| `show_catalog_items`   | `catalog:read` | Up to 12 chosen catalog items as a grid of product cards, shown once with the agent’s final picks.                                                                                                                                                                    |
| `get_reference_photos` | `catalog:read` | Real product photos for one or more catalog ids, so a vision-capable agent can compare them against a render or a user’s photo.                                                                                                                                       |

Dealer-only items and typicals appear only to a workspace with an active owner or dealer relationship with their manufacturer; to anyone else they read as unknown ids.

### Product documentation

| Tool          | Scope       | What it does                                                                                                                                           |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `search_docs` | `docs:read` | Search product documentation — family composition rules, dimension tables, named assemblies, an item’s attach points and configuration — by free text. |
| `get_docs`    | `docs:read` | Fetch one product doc by id (`family:<familyId>` or `item:<catalogId>`): its summary and section list, or one section’s full text.                     |

These are about furniture products already found with `search_catalog`, not about this developer documentation. `docs:read` is elevated: it is granted per client, never by default.

### Quotes and customers

| Tool                   | Scope                            | What it does                                                                                                                                                                               |
| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `search_customers`     | `quotes:read`                    | Find customers in the workspace by name or email.                                                                                                                                          |
| `get_quote`            | `quotes:read`                    | One quote with its customer, lines, totals, and Present link. Dealer cost and margin appear only with `quote_costs:read`.                                                                  |
| `preflight_order`      | `quotes:read`                    | Check an order (SIF or OFDA XML text, or the order a quote exports) against the manufacturer’s price book: part numbers, options, required choices, and prices. Reports only; never edits. |
| `list_discount_tables` | `quote_costs:read`               | The workspace’s discount tables and their revisions, so a quote can be priced against a named one.                                                                                         |
| `save_customer`        | `quotes:read` and `quotes:write` | Create or update a customer. Creating with an email that already exists returns the existing customer instead of a duplicate.                                                              |
| `save_quote`           | `quotes:read` and `quotes:write` | Create or update a quote, optionally with a batch of line changes. Line changes run in order and are not transactional: a failure reports what was applied.                                |
| `present_quote`        | `quotes:read` and `quotes:write` | Publish the quote’s customer-facing Present link and return its URL. Idempotent. It does not send email.                                                                                   |
| `quote_from_spaces`    | `quotes:write`                   | Create a quote seeded from several rooms of one project, one group of lines per room.                                                                                                      |
| `add_room_to_quote`    | `quotes:write`                   | Append one room’s lines to an existing quote, or re-seed a room already on it.                                                                                                             |

`quotes:write` and `quote_costs:read` are elevated scopes. Money in a quote result is in integer minor units (cents for USD), the same as the [REST `/v1` API](/docs/api#v1-beta).

### Embeds

| Tool                       | Scope                           | What it does                                                                                                                                          |
| -------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manage_item_embeds`       | `embeds:write`                  | Mint, list, update, or revoke [single-item embed](/docs/embed) tokens.                                                                                |
| `item_embed_stats`         | `embeds:read` or `embeds:write` | 30-day daily view, selection, and open counters for one embed token. Unknown tokens read as all-zero, never an error.                                 |
| `manufacturer_embed_stats` | `embeds:read` or `embeds:write` | 30-day roll-up of embed activity across every workspace for one manufacturer. Requires the manufacturer’s owner relationship; a dealer gets an error. |

Embed tools are limited to items from manufacturers your workspace works with, as the manufacturer or as a dealer. A dealer sees only its own workspace’s tokens.

## Skills

The server offers the skills Sunny’s agent works from, through the MCP [Skills extension](https://modelcontextprotocol.io/seps/2640) (`io.modelcontextprotocol/skills`). A client that supports it lists them with `skills/list`; any client can read them as Markdown resources.

| Skill         | URI                                  | What it covers                                                                              |
| ------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `room-layout` | `skill://sunny/room-layout/SKILL.md` | How to lay out a room: seating, clearances, circulation, and recipes for common room types. |

Supporting files sit beside each `SKILL.md`, for example `skill://sunny/room-layout/references/conference.md`. Every authenticated caller can read them; no extra scope is needed.

## Example call

POST /mcp — token with projects:read

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "export_layout",
    "arguments": { "spaceId": "spc_k3m9x1q4z8f2" }
  }
}
```

200 OK

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"format\":\"sunny-layout\",\"version\":1,...}"
      }
    ]
  }
}
```

A tool-level failure — wrong scope, unknown id, an invalid document — comes back as a JSON-RPC *success* envelope whose result carries `isError: true` and a readable message. That’s the MCP convention for business errors, and it’s distinct from a protocol error or the connection-level 401 for a bad token.

Missing scope

```json
{
  "content": [
    {
      "type": "text",
      "text": "insufficient_scope: this tool requires the \"projects:write\" scope, which the presented token does not grant."
    }
  ],
  "isError": true
}
```

## Rate limits

Budgets are per OAuth client and user.

* **60 calls per 60 seconds**, shared by `import_layout`, `export_file`, `create_space`, `render_plan`, `save_customer`, `save_quote`, `present_quote`, `quote_from_spaces` and `add_room_to_quote`.
* **5 calls per 60 seconds** for `manage_item_embeds`. It is the same budget as the REST API’s cost endpoints and embed minting, so calls on either surface count against it.

Calls these tools forward to the REST API also count against that API’s own per-owner limits.

Live edits (`place_item`, `move_item`, `remove_item`, `attach_item`, `configure_item`, `edit_items`, `place_typical`, `fill_slot`) have their own limit of **120 calls per 60 seconds per OAuth client, user, and room**.

Tools that read or write through the REST API on your behalf (catalog search, the quote tools, live edits, `render_view`) also count toward the [REST API’s per-user limits](/docs/api#rate-limits).

Over a limit, the tool returns `isError: true` with a `rate_limited:` message naming the retry window, rather than an HTTP 429.