# SandyWP for AI agents

This page is the connect recipe for Grok Bot, Cursor, Hermes Agent, OpenClaw, and other MCP clients.
Read it before adding SandyWP or calling tools.

## Two different MCP URLs

| URL | What it is | Use it to |
| --- | --- | --- |
| https://app.sandywp.com/mcp | **Product MCP** (69+ tools, OAuth + Bearer) | Create sandboxes, magic-login, deploy, preview private GitHub PRs |
| https://docs.sandywp.com/mcp | **Docs MCP only** (Mintlify search) | Search documentation. It is not the SandyWP API. |

Do not connect to docs.sandywp.com/mcp when you need to spin a WordPress sandbox.

## Connect

### OAuth (preferred)

Point the client at https://app.sandywp.com/mcp and run Connect / Authenticate. SandyWP supports
OAuth 2.1 with PKCE and Dynamic Client Registration. Allowed redirect URIs include:

- `https://www.cursor.com/agents/mcp/oauth/callback` (Cursor web / cloud agents)
- `http://localhost:8787/callback` (Cursor desktop loopback)
- `cursor://anysphere.cursor-mcp/oauth/callback` (Cursor native scheme)
- `http://127.0.0.1:<port>/callback` (Hermes, OpenClaw, and other local loopback clients)

The user approves access in the browser. You never need to paste a token.

### Bearer personal API token (fallback)

If the client cannot complete OAuth, create a key at https://app.sandywp.com/account?tab=keys
and send `Authorization: Bearer swp_…`. A valid Bearer session is fully authenticated;
do not start a second OAuth dance just because discovery documents also advertise OAuth.

CLI that already works: `npx @sandywp/cli` (`npx @sandywp/cli auth login` then `npx @sandywp/cli add`).

## GitHub App — not deploy keys

Private-repo PR previews use the SandyWP GitHub App (installation tokens).
Do **not** mint per-sandbox SSH deploy keys. `sandywp_connect_repository` is the old
per-site Git Deployment path; users with write/maintain (not Admin) get 404 on deploy keys.

If GitHub is not connected for this account, send the human to:

https://app.sandywp.com/account?tab=github

That dashboard **Connect GitHub** button installs the org GitHub App. Never paste an SSH public key.

## sandywp_preview_github_pr

Use this tool to spin a WordPress preview of a private (or public) GitHub pull request.

Arguments:

- `repository` — `owner/repo` or a GitHub URL (`https://github.com/owner/repo` or `…/pull/12`)
- `pullNumber` — pull request number (optional when the URL already includes `/pull/N`)
- `destination` — `plugin` or `theme`
- `folderName` — WordPress slug the code is unpacked into, e.g. `publishpress-cart`
  (this is `wp-content/plugins/{folderName}` or `wp-content/themes/{folderName}`).
  GitHub zipballs unpack to `{repo}-{branch}/`; always use `folderName`, never that zipball root.

The tool creates or reuses a sandbox the same way `@sandywp-bot deploy` does and fetches the
PR head SHA with a GitHub App installation token. It returns quickly with status
`creating`/`deploying` and a site id — poll `sandywp_site_status` until `ready`, then
`sandywp_magic_login`. If the preview is already ready it returns the site URL plus a magic login.

## Cursor marketplace plugin

Install the SandyWP Cursor plugin (marketplace listing, or the `cursor-plugin/` source in
https://github.com/rizaardiyanto1412/sandywp). It points at https://app.sandywp.com/mcp so
Grok Bot / Cursor can InstallPlugin and Connect in one tap. Read this page first.

## Discovery files

- https://sandywp.com/agents (this page, `text/markdown`)
- https://sandywp.com/llms.txt
- https://app.sandywp.com/.well-known/mcp.json
- https://app.sandywp.com/.well-known/oauth-protected-resource