Connect external AI agents: MCP server and WebMCP

You can let an AI agent that runs outside Pinegrow work on your project. The agent inspects pages and CSS through Pinegrow and sends editing commands. Pinegrow checks each batch of commands and applies it to the live page, so the change appears in the page right away and goes into the undo history. The agent doesn't edit your files directly.

There are two ways to connect, depending on where you use Pinegrow:

• Pinegrow Desktop runs a local MCP server. MCP clients such as Codex, Claude Code, Cursor and OpenCode connect to it.
• Pinegrow Online offers its tools through WebMCP to AI agents in browsers that support WebMCP.

Both are new in Pinegrow 10. If you want Codex or Claude Code to work inside the AI Assistant panel instead, see Using OpenAI Codex in Pinegrow or Using Claude Code.

MCP server in Pinegrow Desktop

The MCP server is off by default. When you turn it on, Pinegrow adds an MCP endpoint to its internal webserver. The endpoint only accepts requests from your own computer, and every request must include an access token (the bearer token).

Turn on external access

1. In the AI Assistant panel, click the AI Settings button in the row with Send. You can also choose Support & Settings › AI Settings….
2. Scroll to the MCP server section and check Expose Pine Cone MCP to external clients.
3. Under Connect with, choose your client: Codex, Claude Code, Cursor or OpenCode.
4. Click Copy configuration. The copied text includes your token.
5. Click Save. The server starts accepting connections and the token is activated.

Current endpoint shows the server address, for example http://127.0.0.1:<port>/mcp. Bearer token is a random token that Pinegrow creates for you; it's masked in the dialog. Below Connect with, Pinegrow shows setup instructions and the configuration for the selected client, with the address and token filled in.

Use a fixed port

By default, Pinegrow picks a free port for its internal webserver each time it starts, so the MCP address can change. Pinegrow warns you about this in the MCP server section. To keep the same address:

1. Click Settings… next to Current endpoint. The main Settings dialog opens at Internal Webserver port.
2. Enter a free port number, save the settings and restart Pinegrow.
3. Open AI Settings again, copy the updated configuration and update your client.

If another Pinegrow window already uses the fixed port, the new window uses a free port for now. The configuration shown in that window connects to that window.

Add Pinegrow to your MCP client

Paste the copied configuration into your client's MCP settings. Merge it with the settings you already have instead of replacing the file. Pinegrow names the server pinegrow_desktop.

For Claude Code, Cursor and OpenCode the configuration is JSON. For Claude Code it has this shape:

{
    "mcpServers": {
        "pinegrow_desktop": {
            "type": "http",
            "url": "http://127.0.0.1:<port>/mcp",
            "headers": {
                "Authorization": "Bearer <your token>"
            }
        }
    }
}

Codex uses a TOML section instead:

[mcp_servers.pinegrow_desktop]
url = "http://127.0.0.1:<port>/mcp"
http_headers = { Authorization = "Bearer <your token>" }

Where to paste it:

• Codex: ~/.codex/config.toml. Restart Codex.
• Claude Code: ~/.claude.json. Restart Claude Code and run /mcp to check the connection.
• Cursor: ~/.cursor/mcp.json. Restart Cursor.
• OpenCode: ~/.config/opencode/opencode.json. Restart OpenCode.

For other clients, use the same details: the endpoint uses the MCP Streamable HTTP transport and expects the token in an Authorization: Bearer header. Hosted clients, such as ChatGPT, can't reach an address on your computer. They need a secure HTTPS tunnel to the endpoint, which you set up yourself.

Work with the agent

Keep Pinegrow open and ask the agent for a change in its own chat. The agent can connect while you are on the Pinegrow dashboard and open an existing local project folder. It won't switch projects while the current project has unsaved changes. The MCP server offers one tool, pinegrow_execute_commands. Through it the agent can:

• Read the editor state: the open project, the selected page and elements, open pages and unsaved changes. This is how it understands requests such as "change this heading".
• Work with pages: list project files, open a page, and create a new page or copy one inside the project folder.
• Inspect: find elements, read their code and inspect the CSS rules that apply to them.
• Edit HTML: insert, replace, move and remove elements, change content and attributes, and add or remove classes.
• Edit CSS: change rules in existing stylesheets and style blocks. A CSS change can affect every page that shares the stylesheet.
• Find images: search the project's existing AI Assistant image index.

Each change appears in the page as soon as Pinegrow applies it. Use Undo to reverse it, see History – Undo and Redo. The agent has no save command, so save your work in Pinegrow with File › Save or Cmd/Ctrl+S.

If a command in a batch fails, Pinegrow stops the remaining commands. Changes made by earlier commands in that batch stay in place, so check the page and undo if needed.

Review the agent's changes

If Review AI changes is turned on, Pinegrow creates a revision named Before external MCP edits before each batch that can change the project, and an External MCP edit result revision after it. You can compare them in the History panel.

Creating a revision saves your open documents, including edits you made before the agent started. External MCP edits don't get a review card in the AI Assistant conversation. See Review AI changes and Visual change review and revisions.

What the agent can't do

• It can't change reusable component definitions or Pinegrow component attributes. Make those changes in Pinegrow.
• CMS Mode, Quick Test, read-only projects and other editing restrictions still apply.
• It can't run code, import files from remote addresses, or use the AI Assistant chat and questions.
• Only one external session is active at a time. When another client connects, it replaces the previous session, unless that session is in the middle of a tool call.
• It can't run while an AI Assistant task is running in Pinegrow. Finish or cancel that task first.
• A batch can contain up to 100 commands.

Keep the connection private

Anyone who has the token and can send requests on your computer can edit your projects through Pinegrow. Treat it like a password:

• Don't share the copied configuration or post it in screenshots, issues or chats. Your client's configuration file contains the token too, so keep that file private.
• To revoke the token, click Generate a new bearer token and then Save. Saving closes any connected session. Copy the configuration again and update your clients.
• To stop external access, uncheck Expose Pine Cone MCP to external clients and click Save. Connected sessions are closed.

Pinegrow keeps the token with its other protected credentials, see Pinegrow Data folder and protected credentials. If the PINEGROW_EXTERNAL_MCP_TOKEN environment variable is set when Pinegrow starts, it replaces the stored token. AI Settings then shows a notice instead of the token field. That token must be at least 32 characters long.

If the client can't connect

• Unauthorized (401): the token in the client doesn't match. Copy the configuration again after you change or regenerate the token, and make sure you clicked Save in AI Settings.
• Forbidden (403): the request came from another computer or from a web page. Connect from a client on the same computer through 127.0.0.1.
• Current endpoint reads Not running: Pinegrow's internal webserver isn't running, so there is no configuration to copy. Check Internal Webserver port in Settings and restart Pinegrow.
• The address stopped working after a restart: Pinegrow started on a different port. Set a fixed port as described above.
• Too many requests (429) or busy (503): the server accepts up to 60 requests per minute. Wait a moment and try again.
• The project or page changed: if you close or reload a page, or switch projects while the agent works, Pinegrow cancels the pending commands for it. Earlier changes may remain applied.

WebMCP in Pinegrow Online

WebMCP is a browser feature that lets a web page offer tools to an AI agent working in the same browser. Pinegrow Online uses it to give such an agent access to its editing tools.

There is nothing to turn on. When you open Pinegrow Online in a browser that supports WebMCP, Pinegrow registers its tools automatically. In other browsers nothing changes. Pinegrow registers the tools only when it runs in its own tab, not when it is embedded in another page.

Use an agent with Pinegrow Online

1. Open your project in Pinegrow Online and open the page you want to work on.
2. Ask your browser's AI agent for the change.
3. Watch the result in the page and use Undo if you want to reverse it.
4. Save your changes in Pinegrow as usual.

The agent sees two tools:

• pinegrow_get_command_reference returns the current page, the editing commands available right now and how to use them.
• pinegrow_execute_commands runs a batch of up to 100 commands on the current page.

The commands cover finding elements and reading their code, editing HTML, content, attributes and classes, inspecting and changing CSS, searching project file names and the image index, and uploading an image into the project's images/ folder. Uploaded images must be PNG, JPEG, GIF or WebP files of up to 3 MiB. Uploading adds the image file to the project.

Limitations

• The agent works on the page that is selected in Pinegrow. If you select another page, close or reload it, or switch projects, the session ends. The agent has to call the tools again to work on the new page.
• A session that is idle for 30 minutes ends.
• You can't use WebMCP while an AI Assistant task is running in Pinegrow.
• It can't change reusable component definitions.
• In CMS Mode and Quick Test the agent can only find elements, read their code and edit the content that the page allows. Project-wide searches aren't available.
• WebMCP has no save command.

Related

• Review AI changes
• Using OpenAI Codex in Pinegrow
• Using Claude Code
• AI CSS editing
• Pinegrow Online