AI coding agent

If you already subscribe to 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: no per-token API billing, and you prompt from the agent chat you already use.

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). Everything stays on your machine — the bridge never sees your API keys, deploy tokens, or chat history.

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.

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 with your project loaded

Register @swebsy/mcp as an MCP server in your agent.

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. Artifacts (screenshots, exports) are written under SWEBSY_AGENT_DIR (defaults to a swebsy-agent folder in your 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://app.swebsy.com).

2. Pair Swebsy with your agent

The fastest way is a pairing link — your agent generates it, you click it, done.

Global settings → Coding agents. Copy prompt grabs the ready-made message; the code/port fields are the manual fallback.

1. In Swebsy, open the Global settings gear and go to the Coding agents tab (also reachable from the Pair agent button in the AI Builder panel). Click Copy prompt to grab a ready-made message.

2. Paste that prompt into your coding agent. It runs swebsy_start_pairing and replies with a single-use pairing link (a ?swebsy_pair=… URL).

3. Open that link in the browser where Swebsy is running. Studio connects automatically — no form to fill in. The one-time code is stripped from the address bar once it’s used.

Expected result

The status badge shows Paired, and the panel switches to “Agent connected”. Your coding agent’s swebsy_status tool now reports the connected tab.

Manual entry (fallback)

If your terminal can’t linkify the URL, swebsy_start_pairing also returns the raw code and port. In the same Global settings → Coding agents form, paste the code, leave the port at 37373 unless you changed it, and click Connect.

3. Build from your agent

Prompt your coding agent as usual — it drives the Studio tab through tools like:

Tool	What it does
swebsy_status	Report the connected tab, site, and available tools
swebsy_add_section	Insert a section through the AI Builder’s tool pipeline
swebsy_select_page	Switch the page being edited
swebsy_read_selection	Read the currently selected component
swebsy_get_builder_guide	Fetch Swebsy’s component/style guide for the agent
swebsy_capture	Screenshot the canvas at mobile or desktop width
swebsy_export	Export the static site and/or project JSON to disk

Changes appear on the canvas live. Undo works as usual in the Studio tab.

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 (Coding agents or AI chat tab).

Privacy

• The bridge listens on 127.0.0.1 only — nothing is reachable from the network.
• The 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 codes are one-time and session-only; refresh the code with swebsy_start_pairing any time.

Common issues

not_connected from agent tools — the Studio tab isn’t paired. Make sure the tab is open and pair again from Global settings → Coding agents (or the Pair agent button in the AI Builder panel).

“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.

Status shows “Revoked” — another Studio tab paired with the same bridge and took over the session. Reconnect from the tab you want the 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.