Skip to Main
schemawp
Back to docs

Connecting your AI agent

SchemaWP 1.2.0 introduces a dedicated Agent Connections page that replaces the old How to Connect instructions in Settings. You land on it automatically right after activating the plugin, and you can always get back via SchemaWP → Connections or the Schema Agent menu in the admin bar.

Step 1 on the page is choosing how AI agents will talk to your site:

  • MCP — connect chat apps and MCP-capable clients (Claude.ai, ChatGPT, Claude Code, Cursor, Windsurf) over the Model Context Protocol
  • API — connect any AI chat that can make HTTP requests, using a token-authenticated Agent REST API and a pasteable brief
  • Abilities — expose SchemaWP’s tools as WordPress Abilities for Novamira or the WordPress MCP Adapter (requires WordPress 6.9+; the option is hidden on older versions)

All three methods expose the same tools, the same session briefing, and the same History auditing — pick whichever fits your agent.

Local sites

Developing on LocalWP, localhost, or *.local? Desktop agents can connect directly; Claude.ai and ChatGPT need a public tunnel. See Connecting a local site to AI agents.

Connecting over MCP

With MCP selected, the Configure Agent step shows your MCP Server URL:

https://yoursite.com/wp-json/scwp-acss-mcp/v1/mcp

Copy it, then follow the tab for your client.

Claude.ai

  1. In Claude.ai, go to Customize → Connectors and click + Add Custom Connector
  2. Name it anything (e.g. “ACSS MCP”)
  3. Paste the MCP Server URL into the Remote MCP Server URL field
  4. Click Connect on the newly added connector to start the OAuth handshake
  5. You’re redirected to your WordPress site’s OAuth screen — click Allow
  6. Done — no Application Password needed

ChatGPT

  1. In chatgpt.com, go to Settings → Apps → Advanced Settings and enable Developer mode
  2. From the same panel, click Create app and name it anything
  3. Paste the MCP Server URL into the Connection → Server URL field
  4. Set authentication to OAuth
  5. In the app’s Advanced Settings, set the registration method to Client-Initiated Metadata Discovery (CIMD) or Dynamic Client Registration (DCR) — required for the OAuth flow to work
  6. Accept the terms and hit Create app
  7. Authorize access on your WordPress site’s OAuth screen
  8. Done — no Application Password needed

Claude Code

You no longer need to create an Application Password by hand or encode credentials in a terminal — the Connections page generates a ready-to-paste config for you.

  1. On the Claude Code (App Password) tab, click Generate MCP Config. SchemaWP creates a WordPress Application Password for your account and builds the config block. Generating again replaces the previous SchemaWP MCP password for this client.
  2. Copy the config — the password is included and won’t be shown again after you leave the page
  3. Open ~/.claude.json and merge the block into your existing mcpServers section (or paste the whole object if you don’t have one yet)
  4. Restart Claude Code — the MCP server connects automatically

Cursor / Windsurf

  1. On the Cursor/Windsurf (App Password) tab, click Generate MCP Config and copy the result — it’s shown once
  2. Cursor: Settings → Tools & Integrations → MCP Servers → Add new global MCP server, then paste into mcp.json
  3. Windsurf: Settings → Cascade → Model Context Protocol (MCP) → + Add server, then paste the same block
  4. Restart the app so the MCP server connects with the new credentials

Advanced (OAuth)

Any other MCP client that supports OAuth can connect with just the Server URL. Your site implements OAuth 2.0 with PKCE (RFC 7636), Dynamic Client Registration (RFC 7591), and Client ID Metadata Documents (CIMD), so clients auto-discover everything from two path-scoped well-known URLs:

https://yoursite.com/.well-known/oauth-authorization-server/wp-json/scwp-acss-mcp/v1
https://yoursite.com/.well-known/oauth-protected-resource/wp-json/scwp-acss-mcp/v1/mcp

Security: Authorization Code + PKCE (S256) is the only supported flow — no implicit or client-credentials grants. Redirect URIs must use HTTPS (localhost is allowed for local development), and tokens are single-use and expire after 24 hours.

If MCP won’t connect

The Connections page checks your /.well-known/ discovery URLs and shows a notice when server rewrites block them, with one-click options to switch to the API or Abilities method instead. See MCP Connection Fails: /.well-known/ URL Returns 404.

Connecting over the Agent REST API

The API method is for agents that can make HTTP requests but don’t speak MCP.

  1. Select API as the connection method
  2. Give the connection a friendly name and click Create Connection
  3. Copy the generated brief and paste it into any AI chat that can make HTTP requests — the Bearer token is included and won’t be shown again

See the Agent REST API reference for the full endpoint list and session workflow.

Connecting via WordPress Abilities

On WordPress 6.9+, SchemaWP registers its tools as WordPress Abilities, so hosts like Novamira or the official WordPress MCP Adapter can discover and run them without a SchemaWP token or Application Password. See Connecting via WordPress Abilities.

Managing connections

  • The sidebar switch turns agent connectivity on or off for the whole site — also available from the Schema Agent admin-bar menu
  • Active API connections are listed in the sidebar, where each token can be revoked
  • Regenerating an MCP config replaces the previous SchemaWP Application Password for that client

Verify the connection

Whichever method you used, ask the agent something like “What ACSS tools do you have access to?” — it should answer with live data from your site.

Read also