Getting started

Ten minutes to an operable site.

This is the exact sequence used to build the site you are reading, including the two configuration steps that are specific to running behind a local router with a private certificate authority.

01 · Put the theme and plugins in place

Symlink the checkout into the site rather than copying it, so the running site always reflects the working tree you are editing.

ln -s /path/to/agent-shell-theme              wp-content/themes/agent-shell-theme
ln -s /path/to/agent-shell-theme/agentshell-mcp   wp-content/plugins/agentshell-mcp
ln -s /path/to/agent-shell-theme/agentshell-blocks wp-content/plugins/agentshell-blocks

Activate the theme and both plugins. The theme seeds its configuration from default-config.json on activation; the blocks plugin drains any legacy widget option into the canonical registry.

02 · Give the agent an identity

Application Passwords are the recommended path: the same WordPress account a human would use, scoped to that account, revocable from the profile screen.

wp user application-password create <user> <label> --porcelain

{
  "url":  "https://example.test/wp-json/agentshell-mcp/v1/mcp",
  "user": "<user>",
  "pass": "<application password>",
  "timeout": 60
}
  • The daemon config file must be mode 0600. It holds a credential, so keep it out of the repository and out of shell history.
  • The actor needs manage_options for the MCP surface, edit_theme_options for the theme endpoints, and unfiltered_html if it should write raw HTML into post content.
  • The alternative is a static token in X-AgentShell-Token, which needs both AGENTSHELL_REST_TOKEN and AGENTSHELL_REST_TOKEN_USER_ID defined. Missing either fails closed, and says which one is missing.

03 · Connect a client

The daemon is a stdio MCP server. Any client that speaks stdio can launch it.

{
  "mcpServers": {
    "agentshell": {
      "command": "php",
      "args": ["…/agentshell-mcp-daemon/daemon.php", "--config", "…/.agentshell-mcp.json"],
      "exposure": "direct"
    }
  }
}

With a large tool surface, "exposure": "deferred" keeps the tools out of the model's context until it searches for them. direct declares all of them at once. Choose per client.

04 · Two constants for screenshots

The screenshot tool drives headless Chrome on the server. Two things commonly get in its way, and both are configuration, not code.

Finding the browser

AGENTSHELL_CHROME_BIN

Detection looks for google-chrome, chromium and friends on the server's PATH. A PHP-FPM pool with a trimmed PATH will not find them. Name the binary explicitly.

Trusting the certificate

AGENTSHELL_TRUSTED_CA_FILES

Chromium keeps its roots in an NSS database, not the system store, so a site on a private certificate authority has to name that authority. Certificate verification is never switched off — an unnamed certificate still fails.

define( 'AGENTSHELL_CHROME_BIN', '/opt/google/chrome/chrome' );
define( 'AGENTSHELL_TRUSTED_CA_FILES', '/path/to/site-ca.crt' );

Point AGENTSHELL_CHROME_BIN at the browser binary rather than a shell wrapper: the capture runs with a scrubbed environment, and wrappers that shell out to cat or touch will not survive it.

05 · First calls

→ tools/list
← every tool, with schemas and descriptions

→ tools/call · agentshell_get_capabilities
← { "theme_active": true, "capabilities": { … }, "screenshot_backend": { "label": "AGENTSHELL_CHROME_BIN" } }

→ tools/call · agentshell_inspect
← { "shell": …, "design": …, "zones": …, "widgets": …, "content": … }

Then take a snapshot before you touch anything. agentshell_create_snapshot captures the whole configuration under a name; agentshell_restore_snapshot puts it back. It is the cheapest insurance in the tool set.