Build with ChatGPT, Claude or a coding agent

Connect ChatGPT or Claude (no install)

ChatGPT and Claude can build in your Swebsy Studio directly. There is nothing to install: you add Swebsy to the app, sign in to Swebsy, and click Allow.

Before you start

• A free Swebsy account with a verified email (step 1 creates it)

• ChatGPT: Plus or higher, in a browser at chatgpt.com

• Claude: any plan, including Free (one custom connector)

Click Connect ChatGPT or Claude on the Let your AI build it strip (My sites or Create), or open Settings → Build with AI. Pick ChatGPT or Claude and follow that app’s steps. You don’t need an account first: step 1 is Sign in or create your free account, and the other steps unlock once it’s done (after the emailed code, if you signed up with email). The panel moves on by itself once the app connects.

Claude

1. Sign in or create your free account.
2. Click Add Swebsy to Claude. Claude opens with the name and URL filled in. At Claude’s one-connector limit? Remove the other one first.
3. Check the name and URL, then click Continue (and Add if Claude asks). Claude’s notice that the connector came from an external link is expected.
4. Sign in to Swebsy if it asks, then click Allow.
5. In a new chat, click + → Connectors and make sure Swebsy is on.

ChatGPT

1. Sign in or create your free account.
2. Open ChatGPT Plugins, click +, then Add custom MCP server. No + button? Turn on Developer mode: Settings → Apps → Advanced settings.
3. Name it Swebsy and paste this server URL:

   https://mcp.swebsy.com/mcp

4. Choose OAuth. ChatGPT warns that custom servers aren’t checked by OpenAI. That’s expected: tick I understand and want to continue, then click Create as a plugin.
5. On the Plugins page, open Swebsy and click + to install it.
6. Sign in to Swebsy when it asks, then click Allow.
7. In a new chat, click + and pick Swebsy.

To add Swebsy to Claude by hand instead, open Settings → Connectors → Add custom connector, name it Swebsy and paste the same URL.

Expected result

After Allow, Studio says the app is connected and shows a starter prompt. In Claude, Start building in Claude opens a new chat with the prompt in the message box. In ChatGPT, Copy prompt & open ChatGPT copies it: in a new chat, click + and pick Swebsy, then paste.

On a phone you can connect now. Next time you’re at your computer, open Swebsy Studio — your AI builds there.

Until anything is built, Studio points you back to your AI app: the AI Builder panel shows Now ask ChatGPT to build it (or Claude) with an example prompt to copy, and an empty page’s Ask ChatGPT to build it button copies that prompt for you. If you connected without seeing the welcome message, a one-time Connected to ChatGPT note says the same.

Studio has to be open in a tab while the AI works: your sites live in your browser, not on our servers. If it isn’t open, the AI shows you a link that opens it. One tab holds the connection at a time; another device shows Take over here.

To disconnect, open Settings → Build with AI and click Disconnect next to the app, or remove Swebsy from the app’s own settings.

What it can do: the same tools as a coding agent (see Available tools), minus the three that need your own disk: swebsy_start_pairing, swebsy_upload_asset and swebsy_export. swebsy_capture returns the screenshot to the chat as an image. Read-only tools are marked as such, and deleting a page, section, symbol or asset, or replacing a whole page, is marked destructive, so ChatGPT and Claude can ask before running them.

Privacy (ChatGPT and Claude)

• What Swebsy stores: your account, and a record that you allowed the app (its name, when you allowed it, and its access tokens). Tokens are short-lived and refresh automatically.
• What passes through: each request the AI sends and the result Studio returns, including the page content, settings and screenshots needed to do the job. It goes from the app to your open Studio tab and back, in memory. Swebsy doesn’t keep it.
• Where your sites live: in your browser, as always. Nothing is uploaded unless you turn on cloud sync.
• What stays hidden: the same as for coding agents. API keys, deploy tokens and AI chat history never leave Studio.
• Revoking: Disconnect in Settings → Build with AI ends the app’s access at once, including any request in progress. Deleting your account does the same.
• ChatGPT and Claude process what they receive under their own privacy policies.

Use a coding agent (Claude Code, Codex, Cursor…)

If you already use a coding agent — Claude Code, Codex, Cursor, Windsurf, or any other agent that supports MCP — you can let it drive your open Swebsy Studio tab directly. This is the recommended way to build with AI without adding a separate provider API key to Swebsy. Your coding agent’s own plan, usage limits, and privacy policy still apply.

How it works: your coding agent talks MCP to a small local bridge (@swebsy/mcp), which relays commands to the open Studio tab over a WebSocket on 127.0.0.1 (default port 37373). The relay is local-only, and Studio removes API keys, deploy tokens, and chat history from agent-visible data before it crosses the bridge.

Prefer an API key instead?

You can also connect a provider API key and chat inside Swebsy — see AI builder setup. Both can be configured; when they are, the AI Builder panel shows an Agent ⇄ Chat toggle so you pick which one to use.

Quick start:

1. Run npx -y @swebsy/mcp setup
2. Restart your agent.
3. Ask it: “Build me a landing page with Swebsy.” The first request opens Studio and connects it.

The rest of this page covers each step, pairing by hand, and troubleshooting.

1. Add the bridge to your coding agent

Before you start

• Node.js 20 or newer

• A coding agent with MCP support (Claude Code, Codex, Cursor, Windsurf, …)

• Swebsy open in a browser tab (Home or Studio)

Run one command. It registers @swebsy/mcp with every supported agent it finds on your machine (Claude Code, Codex, Cursor, Windsurf, VS Code):

npx -y @swebsy/mcp setup

It never changes an existing swebsy entry, never rewrites a config file it can’t read, and reports the result for each agent. Running it again changes nothing.

To register it by hand instead:

Claude Code

claude mcp add swebsy -- npx -y @swebsy/mcp

Codex

codex mcp add swebsy -- npx -y @swebsy/mcp

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json inside a project):

{
  "mcpServers": {
    "swebsy": {
      "command": "npx",
      "args": ["-y", "@swebsy/mcp"]
    }
  }
}

GitHub Copilot (VS Code)

code --add-mcp '{"name":"swebsy","command":"npx","args":["-y","@swebsy/mcp"]}'

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "swebsy": {
      "command": "npx",
      "args": ["-y", "@swebsy/mcp"]
    }
  }
}

Other MCP agents

Any agent that can run MCP stdio servers works — register npx -y @swebsy/mcp as a server named swebsy in its MCP configuration.

To use a different port, set the SWEBSY_AGENT_PORT environment variable on the server entry. Set SWEBSY_AGENT_DIR to choose where screenshots and exports are written; without it, the bridge uses .swebsy-agent in the nearest pnpm workspace or its current working directory. To point the pairing link at a non-default Studio origin (local dev or self-host), set SWEBSY_APP_URL (defaults to https://studio.swebsy.com). The bridge opens Studio in your default browser when it needs to pair; set SWEBSY_NO_OPEN=1 to disable that and pair by hand instead.

2. Restart your agent and ask it to build

Global settings → Build with AI shows the same three steps. Pairing by hand folds away under Trouble connecting? Pair by hand.

1. Restart your agent. Agents only load new MCP servers when they start, so it can’t see Swebsy until you quit and reopen it.

2. Ask it: “Build me a landing page with Swebsy.” Any build request works. The first request opens Studio and connects it: the bridge opens a single-use pairing link in your default browser, the new Studio tab connects, and then the agent’s tool call runs (it waits up to 20 seconds).

Expected result

Your agent starts building in the Studio tab that opened. Under Global settings → Build with AI, that tab shows Agent connected and names the agent driving it. Any other Swebsy tab you had open shows Agent connected in another tab. Your agent’s swebsy_status tool reports the connected tab and agent roster.

You connect once per browser: Studio remembers the session, and so does the bridge (in ~/.swebsy). It reconnects after a reload, a lost connection, or the bridge restarting. If no Studio tab is connected when your agent calls a tool, the bridge opens Studio and reconnects it by itself, then runs the tool. If a Swebsy tab is already open, that tab picks the session back up and the new one tells you it can be closed.

In Claude Code, the /swebsy:swebsy (MCP) prompt walks the agent through connecting and opening a site. Other agents show MCP prompts in their own way, if at all.

Pair by hand / troubleshooting

Pair by hand when the first request didn’t connect: the browser didn’t open, Swebsy runs in a different browser, or you set SWEBSY_NO_OPEN=1.

1. Ask your agent to run swebsy_start_pairing and open the link it gives you. The ready-made prompt is under Global settings → Build with AI → Trouble connecting? Pair by hand.

2. Open the returned pairing link (a ?swebsy_pair=… URL) in the browser where you use Swebsy. Studio connects automatically and strips the one-time code from the address bar.

3. If you can’t open the link there, paste the raw code the tool also returns into the same fallback form, leave the port at 37373 unless you changed it, and click Connect.

A pairing link expires after ten minutes and works only once. Your agent drives exactly one Studio tab at a time — see One tab at a time below.

Keep the Studio tab awake

Your agent can only work while the Studio tab is running. If the browser puts it to sleep, tools answer tab_unresponsive until you click the tab. Pinning the tab may help, or add Studio under Chrome’s Settings → Performance → Always keep these sites active.

One tab at a time

Your agent drives exactly one Swebsy tab. If you paired from a different tab than the one you’re working in — or opened your site in a new tab afterwards — that tab shows Agent connected in another tab, in the AI Builder panel and under Global settings → Build with AI. Click Take over here to move the session across; the tab that held it says so and can take it back the same way.

3. Create, open, and build from your agent

Prompt your coding agent as usual. It can list installed templates and saved sites directly from Home, create a blank or template-based site, open a site by ID, and rename a site’s internal Swebsy name. Site IDs are authoritative, so duplicate names are fine. Creating from a template preserves that template’s name and project data; call swebsy_rename_site separately when you want a different internal name.

Creating or opening a site starts Studio navigation. Poll swebsy_status until editorReady is true and siteId is the expected ID before sending editing commands. While Home is open or Studio is loading, status reports siteId: null and editorReady: false.

Most editing tools act on the currently selected page. The agent can switch pages with swebsy_select_page, read component paths and ids with swebsy_read_page, and then edit the intended target by id (which stays valid when other components move) or by path.

A typical site-management workflow

You can give the agent one natural-language request, for example:

List my installed templates, create a site from the portfolio template, wait for it to open, rename it to Northwind Portfolio, and add a Contact page.

The agent should perform the workspace operations in this order:

1. Run swebsy_list_templates and choose the template by its returned id.
2. Run swebsy_create_site with that templateId and keep the returned siteId.
3. Poll swebsy_status until the same siteId is present and editorReady is true.
4. Run swebsy_rename_site with the siteId and new internal name.
5. Use the editing and inspection tools only after the editor is ready.

The same pattern applies to swebsy_open_site: list sites, select by ID, open the site, then wait for the expected ready editor before making changes. The bridge invalidates the previous editor while navigation is in progress, so queued edits cannot land on the site you just left.

Creation and naming rules

Action	Behavior
swebsy_create_site {}	Creates Swebsy’s standard blank project with its automatic name and default content
swebsy_create_site { templateId }	Imports the selected template unchanged, including its name, pages, styles, symbols, and assets
swebsy_rename_site { siteId, name }	Trims the name and changes only the internal name shown on Home and in the Studio topbar
Change the browser or search-page title	Use the site’s SEO/public title settings; renaming the internal project does not change those fields

Creation deliberately has no name argument. Create or import first, then rename the resulting site explicitly. Copying and deleting sites are not available to agents; use the Project menu for those actions.

What workspace tools return

• swebsy_list_templates refreshes the installed catalog and returns template IDs, names, descriptions, tags, fonts, preview URLs, and thumbnail URLs.
• swebsy_create_site returns siteId, name, source, optional templateId, and studioPath before the paired tab navigates.
• swebsy_list_sites returns sites newest-first with only id, internal name, status, timestamps, optional templateId, pageCount, and isOpen. It does not return page content, thumbnails, assets, revisions, or settings.
• swebsy_open_site returns that site’s metadata. Opening the already active site is safe and does not reload Studio.
• swebsy_rename_site returns the updated metadata and refreshes the name on Home and in the Studio topbar.

Use multiple coding agents

You can connect several coding agents to the same open Studio tab at once. For example, Claude Code and Codex can work side by side on the same project:

1. Register @swebsy/mcp in each coding agent and start both agents.
2. Keep every MCP server on the same SWEBSY_AGENT_PORT (the default is 37373). The first server starts the shared local relay; the others join it automatically.
3. Pair the Studio tab once. You do not need a separate pairing code for each agent.

The AI Builder panel lists every connected agent, shows whether each is Working or Idle, and tags activity with the agent that initiated it. swebsy_status returns the same connected-agent roster.

One Studio tab, several agents

All connected agents share one paired Studio tab. The relay runs one editor command at a time, so commands from other agents wait in a shared queue instead of mutating the canvas concurrently. Pairing a different Studio tab to the same relay revokes the previous tab.

Screenshots and exports are returned only to the agent that requested them and are written to that MCP server’s SWEBSY_AGENT_DIR. To reduce conflicting intent, give agents separate pages or areas of responsibility and have them inspect current state before editing shared content.

Available tools

Sites and templates

Tool	Input	What it does
swebsy_list_templates	None	Refresh and list installed templates with metadata, preview URLs, and thumbnail URLs
swebsy_create_site	Optional templateId	Create the standard blank site or import a template unchanged, then open it in Studio
swebsy_list_sites	None	List saved sites newest-first as metadata only, including IDs, page counts, and open state
swebsy_open_site	siteId	Validate and open a saved site by ID; does nothing disruptive when that site is already open
swebsy_rename_site	siteId and non-empty name	Change only the internal Home/Studio site name, without changing SEO or the deployed-page title
swebsy_publish	None	Put the open site live on Swebsy Hosting (free swebsy.site address) once you say yes

Build and edit

Tool	What it does
swebsy_commit_design_direction	Commit the site to a visual direction — type, palette, topology — and apply it. Call once before building a new site
swebsy_replace_page_content	Replace every top-level section on the selected page; does not create a page
swebsy_create_page	Create a blank page, select it by default, and return its ID and filename
swebsy_link_page	Point an existing navbar link, link, or button at a project page
swebsy_update_page	Rename a page or change its URL slug; links to the old slug follow
swebsy_duplicate_page	Copy a page into a new page and select it
swebsy_delete_page	Delete a page; the home page and a site’s last page are refused
swebsy_add_section	Insert a section, from a component tree or plain HTML, at the start, end, or next to a given targetPath
swebsy_edit_section	Replace or patch the selection or a component path from swebsy_read_page
swebsy_delete_section	Remove the selection or a component path from the page (never empty it instead)
swebsy_move_section	Move a component before or after another, keeping its ID and styles
swebsy_wrap_section	Wrap sibling components in one element, e.g. <main>, keeping their IDs and styles
swebsy_duplicate_section	Copy a component and insert the copy right after it
swebsy_insert_block	Insert a catalog block, with optional adaptations and targetPath placement
swebsy_update_settings	Change any site setting: SEO, fonts, theme, favicon, robots.txt and sitemap, analytics, custom code, deploy target
swebsy_animate_page	Apply Swebsy’s scroll-reveal system to the current page or every page
swebsy_undo	Revert the agent’s own last editing tool call(s) this session, up to 20
swebsy_redo	Re-apply tool calls reverted by swebsy_undo

Navigate, inspect, and reuse

Tool	What it does
swebsy_status	Report relay/tab state, internal site name, editor readiness, page, viewport, and tools
swebsy_list_pages	List every page with its ID, name, file name, section count, and which one is selected
swebsy_select_page	Select a page by ID or name
swebsy_read_page	Read the selected page structure and addressable paths; flags symbol mains, instances, and per-instance overrides
swebsy_read_selection	Read the currently selected component’s type, classes, attributes, and text
swebsy_list_blocks	List block IDs and labels available to swebsy_insert_block
swebsy_get_builder_guide	Load the component, theme-class, and builder conventions used by Swebsy
swebsy_list_skills	List available deep-guidance skills and their summaries
swebsy_get_skill	Load the full instructions for one guidance skill
swebsy_list_symbols	List reusable symbols, instance counts, and page counts
swebsy_promote_to_symbol	Turn a component path into a reusable symbol
swebsy_add_symbol_instance	Add a linked symbol instance at the start or end of the selected page
swebsy_detach_symbol	Turn one symbol instance back into a plain component
swebsy_rename_symbol	Rename a symbol
swebsy_delete_symbol	Delete a symbol; its instances stay on their pages as plain components

Before building a repeated custom component — cards, link blocks with hover effects, testimonials — have the agent load the symbols skill (swebsy_get_skill). It explains how to build one symbol and repeat it with different content per instance while the styling stays in sync, which also keeps those sections harvestable as reusable blocks.

Connection and files

Tool	What it does
swebsy_start_pairing	Open a single-use pairing link in the browser and return it plus the fallback code and port
swebsy_capture	Save a page, section (targetPath), or selected-component PNG at a fixed responsive viewport
swebsy_list_assets	List managed assets and their whole-project usage counts
swebsy_upload_asset	Put a local image, font, video, audio, or PDF file into the site and return how to use it
swebsy_delete_asset	Delete a managed asset; refuses live references unless force: true
swebsy_export	Write the static site and, optionally, portable project JSON and assets

swebsy_upload_asset is how an agent gets your imagery into a site — screenshots, logos, textures, product mockups. Give it an absolute path to a .png, .jpg, .webp, .gif, .avif, or .svg (up to 10 MB) and it returns the asset src to set on an image component. Pass paths (up to 25) instead of path to upload a whole set in one call; it returns a map of file name to src. Without it, an image with no src falls back to a random stock photo.

It also takes video (.mp4, .m4v, .webm, .mov, .ogv), audio (.mp3, .m4a, .wav, .ogg) and .pdf files, and returns a ready-made video, audio or download-link snippet. The 10 MB limit matches the largest file Swebsy Hosting publishes, so compress longer videos first — H.264 .mp4 at 1080p or less — or point the video at a hosted URL instead.

It also takes a .woff2, .woff, .ttf, or .otf font. Fonts are stored alongside your uploaded fonts rather than in the image library, and the agent passes the returned ID to swebsy_update_settings to add the font to the site.

Prefer .svg for logos and other flat vector art so it stays sharp at any size. Uploaded SVG is sanitized before it is stored — scripts, event handlers, and references to external URLs are stripped — so a logo downloaded from the web is safe to drop straight in. The same sanitizing applies to SVG you upload by hand in the Studio asset manager.

Changes appear on the canvas live. To take back an agent edit, ask the agent to undo it (swebsy_undo) — agent edits don’t go on the Studio undo stack, so Cmd+Z in the tab won’t revert them. If you’ve edited the same page by hand since, the agent’s undo stops rather than overwrite your change.

Switching between agent and API key

There’s no mode setting to flip — the AI Builder panel just shows whatever you’ve configured. Set up only a coding agent and it shows Agent connected; set up only an API key and it shows the chat. When both are configured, the panel shows an Agent ⇄ Chat toggle so you can switch surfaces per session. Configure either one from the Global settings gear (Build with AI or AI chat tab).

Privacy

• The bridge listens on 127.0.0.1 only — nothing is reachable from the network.
• Studio redacts secrets before anything crosses the bridge: your AI API keys, deploy tokens, and AI chat history are never sent to the agent.
• Pairing grants every connected agent permission to edit the open project, including every setting in the Settings window: SEO, fonts, theme, favicon, robots.txt, analytics, security headers, custom code, and the deploy target (repository, account, or subdomain).
• Agents can never set or read deploy tokens: paste those yourself in Settings → Deployment. They also can’t touch your AI provider keys or chat history.
• Custom code runs on every page of your published site. When an agent (or the in-app AI Builder) changes it, Studio shows a warning that stays until you close it. Review the change in Settings → Advanced and Analytics before you publish.
• Workspace tools can receive installed-template metadata and saved-site metadata (including internal site names, IDs, timestamps, template IDs, and page counts). Site listing does not return page content, thumbnails, assets, revisions, or settings.
• The agent can create, open, and rename local sites. Creation and rename analytics include only source/template/site IDs; internal names and site content are not included.
• The agent can receive the non-secret site content, settings, screenshots, and exports needed to complete editing requests. Your coding agent may process that data through its own service, so its privacy policy still applies.
• Pairing codes are single-use and expire after ten minutes; refresh the code with swebsy_start_pairing any time.
• The session token is stored in ~/.swebsy/agent-<port>.session, readable only by your OS user. Pairing with a new code replaces it.

Common issues

not_connected from agent tools — no Studio tab connected within 20 seconds. Click your Swebsy tab (it may be asleep), or open the link in the error message, then retry. If nothing opens, pair by hand — see Pair by hand / troubleshooting above.

tab_unresponsive — the Studio tab is connected but the browser has put it to sleep. Click the tab, then retry. See Keep the Studio tab awake above.

“Could not reach the MCP bridge” — the bridge isn’t running on that port. Check the MCP server is registered and running in your agent, and that the port in Swebsy matches SWEBSY_AGENT_PORT (default 37373).

Pairing rejected — links and codes are one-time. Ask the agent to run swebsy_start_pairing again, then open the fresh link or paste the fresh fallback code.

Only one agent appears — make sure every agent’s MCP server is running and uses the same SWEBSY_AGENT_PORT. Run swebsy_status to inspect the shared roster. Pair Studio once to the shared relay rather than generating a code for each agent.

An agent waits while another is working — this is expected. The shared relay serializes commands so only one mutation runs in Studio at a time.

“Agent connected in another tab” where you expected the chat — another Swebsy tab, not another coding agent, holds the session. Only one tab can hold it. Click Take over here in the tab you want your agent to drive.

Agent connected but the AI Builder chat is gone — that’s by design: while an agent is paired you prompt from the coding agent, not the panel. If you also have an API key set, use the panel’s Agent ⇄ Chat toggle to get the built-in chat back.