Agent integration guide

Version 1.1 · Public Streamable HTTP MCP · One source photo, one image credit, one saved design.

Connect any compatible client

1. Sign in to your existing Room & Story account and review the upload notice in Data & privacy.
2. Open Agent connections. Name the agent, set its render allowance and expiry, and create a key. Set the allowance to zero for read-only access.
3. Configure your MCP client with the endpoint and secret header below. Each person uses their own key and account.

https://roomandstory.com/api/mcp

{
  "mcpServers": {
    "room-and-story": {
      "type": "http",
      "url": "https://roomandstory.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_KEY"
      }
    }
  }
}

This is a generic configuration example for clients that support Streamable HTTP and custom headers. Client configuration layouts vary. Keep the actual key in the client’s secret settings; do not commit it or paste it into a prompt. This endpoint uses account keys, not automatic OAuth sign-in.

Sign in with the same provider you use in Studio. Google, email and ChatGPT accounts are supported through their existing login flows; separate account projects are not silently merged. No Site-owner invitation or private plugin installation is required for this endpoint.

Check the connection

Send initialize, then notifications/initialized and tools/list. The server is stateless and returns JSON responses. It supports protocol versions 2026-07-28, 2025-11-25 and 2025-06-18. Send the Authorization header on every request. GET returns 405 because no server event stream is offered.

Download the example client for a connection check or a quoted render using a local room photo. Read its instructions before enabling generation.

Run the workflow

1. Call get_capabilities to read current room names, style IDs, palette IDs and limits.
2. Call upload_image with mime and raw base64 data. Maximum decoded size: 9 MiB. Save the returned image id.
3. Call quote_project. Keep the returned opaque quote and job_id. A quote costs no credits and reserves no capacity.
4. Within the user’s authorized budget, call create_render with that quote and max_credits: 1. This spends at most one existing image credit and one slot in the key’s render allowance.
5. Call get_job with id: job_id, at most once every 15 seconds, until completed or failed.
6. Call export_project with the job ID. Use agent_download_url and the same Authorization header for a full-resolution download. Set include_image: true for an inline preview.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "quote_project",
    "arguments": {
      "source": "<uploaded-image-id>",
      "name": "Apartment living room",
      "mode": "staging",
      "room": "Living room",
      "style": "minimal",
      "palette": "quiet"
    }
  }
}

OpenAPI specification · Tool schemas · MCP Registry metadata · Documentation index

Retries, budgets and failures

Reuse the exact quote for every submission retry within its 15-minute validity. Its job ID is fixed, and atomic render reservation prevents a second charge. After a timeout or an expired quote, check the saved job ID first. Never create a new quote automatically to resolve an uncertain submission.

The key’s total render allowance is enforced on the server, including concurrent submissions. Accepted renders count toward the allowance even when a technical failure returns the image credit. This bounds attempts as well as spending. Keys expire within 90 days and can be revoked from Agent connections. No tool buys credits, changes consent, deletes designs or publishes them.

An invalid, expired or revoked key returns HTTP 401. MCP tool failures return isError: true. Missing consent needs user action. Insufficient credits or an exhausted key allowance need an account-owner decision. Capacity or worker outages should be retried later using the same quote.

Files and privacy

Keys can read and download their owner’s saved designs. Only keys with a positive render allowance can upload and generate. Every operation remains scoped to that account. Downloads with agent_download_url require the same secret header; browser download URLs require the signed-in owner. Neither is a public sharing link.

Present the original beside the After · Room & Story concept label. Review the result before property marketing. Free-credit results retain the standard watermark.

Optional Sites connection

The separate Sites-managed plugin uses https://roomandstory.jasoncma7.chatgpt.site/mcp as both endpoint and OAuth resource. Keep using it if already connected. The public account-key endpoint above works independently.