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.
Endpoint
Section titled “Endpoint”POST https://agents.sunnysdk.com/mcp — stateless
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.
Content-Type: application/jsonAccept: application/json, text/event-streamAuthorization: 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
Section titled “Connecting”-
Find the authorization server.
GET /.well-known/oauth-protected-resourceonagents.sunnysdk.comreturns RFC 9728 metadata naming the authorization server and its scopes. A 401 from/mcpcarries the same URL in aWWW-Authenticateheader, so a compliant client can find it with no out-of-band config.GET https://agents.sunnysdk.com/.well-known/oauth-protected-resource {"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. -
Register a client. Preferred: host a JSON Client ID Metadata Document at a public HTTPS URL (MCP 2026-07-28 profile — the document needs
client_nameandredirect_uris) and use that URL as yourclient_iddirectly; no registration call needed. See Registering a client for the document shape. RFC 7591 Dynamic Client Registration atPOST https://auth.sunnysdk.com/api/auth/oauth2/registerstill works as a fallback for a client that can’t serve a metadata document. -
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 for what each one grants. -
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.
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
Section titled “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 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
Section titled “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
Section titled “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
Section titled “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.
Embeds
Section titled “Embeds”| Tool | Scope | What it does |
|---|---|---|
manage_item_embeds |
embeds:write |
Mint, list, update, or revoke single-item 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
Section titled “Skills”The server offers the skills Sunny’s agent works from, through the MCP
Skills extension (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
Section titled “Example call”{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "export_layout", "arguments": { "spaceId": "spc_k3m9x1q4z8f2" } }}{ "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.
{ "content": [ { "type": "text", "text": "insufficient_scope: this tool requires the \"projects:write\" scope, which the presented token does not grant." } ], "isError": true}Rate limits
Section titled “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_spacesandadd_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.
Over a limit, the tool returns isError: true with a rate_limited: message naming the retry
window, rather than an HTTP 429.