Skip to content

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.

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.

Required headers
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.

  1. Find the authorization server. GET /.well-known/oauth-protected-resource on agents.sunnysdk.com returns RFC 9728 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
    {
    "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 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 for the document shape. RFC 7591 Dynamic Client Registration 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 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.

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.

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.

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.

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.

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.

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.

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.

POST /mcp — token with projects:read
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "export_layout",
"arguments": { "spaceId": "spc_k3m9x1q4z8f2" }
}
}
200 OK
{
"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
{
"content": [
{
"type": "text",
"text": "insufficient_scope: this tool requires the \"projects:write\" scope, which the presented token does not grant."
}
],
"isError": true
}

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.

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