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_optionsfor the MCP surface,edit_theme_optionsfor the theme endpoints, andunfiltered_htmlif it should write raw HTML into post content. - The alternative is a static token in
X-AgentShell-Token, which needs bothAGENTSHELL_REST_TOKENandAGENTSHELL_REST_TOKEN_USER_IDdefined. 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.
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.
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.