Skip to Main
schemawp
Back to docs

Connecting a local site to AI agents

This guide covers connecting a local WordPress site running SchemaWP Pro to the AI agents listed on SchemaWP → Connections. It applies to LocalWP, MAMP, Docker, *.local, localhost, and similar development environments.

For production sites, follow Connecting your AI agent. The Connections page steps are the same here — the difference is whether the agent can reach your machine.

Desktop vs cloud agents

Pick the path that matches where the agent runs:

  • Desktop agents (Cursor, Claude Code, Windsurf, VS Code, GitHub Copilot, Antigravity, Codex) run on your computer. They can call your local MCP or Agent REST URL directly — no public tunnel required.
  • Cloud agents (Claude.ai, ChatGPT) run on the vendor’s servers. They cannot see localhost or *.local. You must expose the site with a public HTTPS tunnel before OAuth will work.

Before you connect

  • SchemaWP Pro is active and Automatic.css is available on the local site.
  • In Settings → General, WordPress Address and Site Address match the URL you open in the browser (including http vs https and any port).
  • On Connections, the agent connectivity switch in the sidebar is turned on.
  • The MCP Server URL shown on Connections should look like your real local origin, for example https://yoursite.local/wp-json/scwp-acss-mcp/v1/mcp or http://localhost:10003/wp-json/scwp-acss-mcp/v1/mcp.

Desktop agents (recommended)

For local development, prefer the Application Password tabs on Connections. They skip OAuth discovery (/.well-known/) and work well against local HTTP or HTTPS.

Steps

  1. Open SchemaWP → Connections and select MCP.
  2. Open the tab for your client (Cursor, Claude Code, Windsurf, VS Code, GitHub Copilot, Antigravity, or Codex).
  3. Click Generate MCP Config. SchemaWP creates a WordPress Application Password and builds a ready-to-paste block. Generating again replaces the previous SchemaWP MCP password for that client.
  4. Copy the config immediately — the password is shown once.
  5. Paste it into the client’s MCP settings (paths and UI labels match the instructions on that Connections tab).
  6. Confirm every URL in the config uses your local origin (not a staging or production domain).
  7. Restart or reload the client so it picks up the new server.

WordPress Application Passwords are available in local development environments even when the site is not on public HTTPS.

Optional: OAuth from a desktop client

Cursor’s one-click deeplink, Claude Code’s CLI OAuth flow, and the Advanced (OAuth) tab can still work locally when the client can open your site’s authorize URL in a browser. Redirect URIs may use loopback HTTP (localhost). If discovery fails, stay on Application Password configs — they do not need /.well-known/.

Cloud agents (tunnel required)

Claude.ai and ChatGPT must reach your WordPress site over the public internet. Expose the local site with a stable HTTPS URL, then connect as you would on a live site.

1. Expose the local site

Use any HTTPS tunnel that forwards to your local WordPress origin, for example:

  • Cloudflare Tunnel
  • ngrok
  • LocalWP Live Link (or similar share features)

Keep the tunnel running while you connect and while you use the agent.

2. Align WordPress URLs with the tunnel

MCP and OAuth URLs are built from your Site Address. While connecting a cloud agent, the public URL the agent calls must match what WordPress thinks the site is:

  • Temporarily set WordPress Address and Site Address to the tunnel HTTPS URL, or
  • Configure the tunnel so it preserves the same host WordPress already expects and still serves that host publicly.

After connecting, you can restore your local Site Address for day-to-day work — but the cloud connector will keep calling whatever public URL you registered. Prefer a stable tunnel hostname if you will reconnect often.

3. Connect from Claude.ai or ChatGPT

On Connections, open the Claude.ai or ChatGPT tab and follow the same OAuth steps as for a production site. The MCP Server URL should use the tunnel origin, for example:

https://your-tunnel.example/wp-json/scwp-acss-mcp/v1/mcp

Cloud clients discover authentication via path-scoped well-known URLs. Those must return JSON on the tunnel URL:

https://your-tunnel.example/.well-known/oauth-authorization-server/wp-json/scwp-acss-mcp/v1
https://your-tunnel.example/.well-known/oauth-protected-resource/wp-json/scwp-acss-mcp/v1/mcp

If discovery returns 404, see MCP Connection Fails: /.well-known/ URL Returns 404.

Agent REST API on a local site

The API method on Connections works the same locally. Create a connection, copy the pasteable brief, and give it to an agent that can make HTTP requests.

  • Desktop agents can call the local Agent REST base URL directly.
  • Cloud chats that fetch over HTTP need the same public tunnel as MCP, and the brief’s base URL must use that public origin.

See the Agent REST API reference for endpoints and the bootstrap workflow.

WordPress Abilities on a local site

On WordPress 6.9+, SchemaWP registers tools as Abilities for Novamira or the WordPress MCP Adapter. The consumer still needs a reachable WordPress site:

  • A desktop Novamira / adapter install on the same machine can use the local site URL.
  • A remote host needs a tunnel (same constraints as cloud MCP).

See Connecting via WordPress Abilities.

Common pitfalls

  • Wrong origin in the config — pasted MCP JSON still points at staging or production while you are testing locally.
  • HTTP vs HTTPS mismatch — browser uses https://yoursite.local but the config still says http:// (or the reverse).
  • Application Passwords unavailable — enable them for local environments, or use HTTPS / a recognized local setup so WordPress allows App Passwords.
  • Tunnel URL changed — free tunnels often rotate hostnames; re-align Site Address and reconnect the cloud connector.
  • Well-known blocked on the tunnel edge — cloud OAuth fails even though /wp-json/ works; check the discovery URLs above.
  • VPN or firewall — desktop agents on another machine or network still cannot reach a private local IP without a tunnel or shared network path.

Verify the connection

Ask the agent something like “What ACSS tools do you have access to?” — it should answer with live data from your local site.

Read also

Read also