AI Agents (MCP)

PhantomWP speaks the Model Context Protocol (MCP), the standard AI coding agents use to call outside tools. Connect an agent such as Claude Code, Claude Desktop, Codex or Cursor, and it can work on your PhantomWP sites with the same tools the built-in AI Assistant uses: it edits files, checks and builds the site, takes screenshots of the preview, and models WordPress content. You watch the live preview update as it goes.

There are two connections, and you can use one or both:

Setting Up a Connection

Both dialogs work the same way:

1. Pick your client: Claude Code, Claude Desktop, Codex, Cursor, or Other for any MCP client.
2. Click Generate connection. This creates a personal access token (it starts with pwp_) and setup made for your client.
3. Copy the setup into your client:
   • Claude Code: paste the prompt into Claude Code, or run the claude mcp add command in your terminal.
   • Claude Desktop: add the snippet to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop. Requires Node.js on your machine.
   • Codex: add the snippet to ~/.codex/config.toml.
   • Cursor: add the snippet to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects.
   • Other: use the connection details (server URL and Authorization header).
4. Send the first prompt the dialog gives you. It tells the agent how PhantomWP projects work and the rules to follow (for example, never push or discard changes without asking).

For Claude Code, registering the account connection looks like this:

claude mcp add --transport http --scope user phantomwp "https://phantomwp.com/api/mcp-server" \
  --header "Authorization: Bearer pwp_..."

Most clients load MCP servers when they start. If the agent can't see the PhantomWP tools after you add them, restart the client.

The Account Connection

The account connection is for everything that happens before you open a project. It needs an account-wide token, so set it up from the dashboard; tokens made for one project are refused.

PhantomWP's servers can't see your computer, so the agent runs the Docker commands itself, in its own terminal. It first checks that Docker is installed and running, and if it isn't, tells you what to install or start. The agent asks you before it removes or recreates a container that already exists.

The agent can also keep your containers up to date. When get_runtime_status reports a newer version, ask it to update the project: it runs the update command, which pulls the new version and recreates the container. Your project files are kept, the same as with Update container on the dashboard.

A typical first session:

The agent creates the project, runs the docker run command, checks get_runtime_status until the project reports ready (the first start installs dependencies and can take a few minutes), and gives you the preview URL. By default the project files go in a phantomwp/<project> folder in your home folder, so you can open them in any editor.

The Project Connection

The project connection gives the agent the tools for building the site:

• Files: read, search, create, edit, rename and delete files
• Checks: run_astro_check, run_build and the dev server logs
• Preview: screenshot_preview to see the rendered page
• Runtime: restart_services and install_package
• Git: status, diff, branches, commit and push
• WordPress: the schema, real sample content, and the scaffold tools (see below)

Every change hot-reloads, so the site updates in the preview while you watch. get_project_info and ensure_runtime work even while the project is stopped: the agent uses them to find out where things stand and to start Fly and Codespace projects.

Local Docker Projects

Projects in Docker on your machine connect differently. PhantomWP's servers can't reach a container on your computer, so the agent talks to a server that runs inside the container, started with docker exec:

docker exec -i -w /app phantomwp-<project> node /app/.phantomwp/mcp/server.mjs

The editor's Connect AI Agent dialog shows this command already set up for your client. Through it the agent gets:

• Checks and preview: run_astro_check, run_build, get_dev_server_logs, restart_services and screenshot_preview
• WordPress: the schema, sample content and the scaffold tools

If your project files are in a folder on your machine (the default), the agent edits them there directly, with its own file tools, and the dev server hot-reloads.

To use the WordPress scaffold tools from Docker, click Enable scaffold tools in the dialog. This adds a project-scoped token to the command (-e PHANTOMWP_MCP_TOKEN=pwp_...). Use this token for the container and keep your account-wide token in the account connection. An environment variable set in your client's config won't reach the container, so it has to be part of the docker exec command. Keep scaffold tokens out of the project's .env files, which build tools can read.

WordPress Tools

Both connections and the Docker server let an agent read your WordPress site before it writes code against it:

• get_wordpress_schema: post types, taxonomies and the custom fields on each
• fetch_wp_sample: one real post with its actual field values
• browse_content (Docker server): list and search published content

The scaffold tools go further and change WordPress itself: register custom post types (wp_register_post_type), taxonomies (wp_register_taxonomy) and field groups (wp_register_field_group), and create or remove demo content (wp_create_posts, wp_delete_managed_posts). They need two things:

1. The PhantomWP Connect plugin with scaffold writes turned on in wp-admin → PhantomWP.
2. Your approval: MCP clients ask before each call that changes something.

Security

• Tokens are stored only as a hash and shown once. Project tokens reach one project; account tokens reach all of them. Revoke any token from either dialog.
• Approval: your MCP client asks before each tool call that changes something (Claude Code prompts per call unless you allow it for the session).
• WordPress writes stay off until a site admin turns on scaffold writes in wp-admin, and deleting demo content only removes posts PhantomWP created.

Troubleshooting

The agent doesn't see the PhantomWP tools

Restart your client after adding the server. In Claude Code, run /mcp to see connected servers and their status.

"Unauthorized" or "This token is scoped to one project"

The token was revoked, expired, or is the wrong kind. The account connection needs a token from the dashboard's Connect AI agent dialog; generate a new one there.

Status says "unknown" for a local project

The container hasn't reported in recently: it may not exist, or it runs an older image. The agent can check it itself with the commands get_runtime_status returns, or update the container.

spawn docker ENOENT in Claude Desktop or Cursor

Desktop apps on macOS don't always see your shell's PATH. Use the full path to Docker in the config, for example /usr/local/bin/docker.

The checks and preview tools are missing in Docker

The project needs infrastructure update 1.54.0 or later. Open the Infrastructure modal in the editor and apply updates, then restart your client.

Next Steps

• Docker Local Development: run projects on your own machine
• AI Assistant: the AI built into the editor
• Claude Code CLI: run Claude Code inside a Codespace terminal