Connect your AI

How to connect your AI to WordPress

This guide walks you through connecting an external AI agent (Claude Desktop, ChatGPT, Cursor, Codex, etc.) to your WordPress site so it can call Maxi AI Core abilities.

Before you begin: make sure you’ve completed Installation and your license is active.

How It Works

Maxi AI Core exposes its abilities through the MCP Adapter, which serves a single JSON-RPC endpoint at:

https://yoursite.com/wp-json/mcp/mcp-adapter-default-server

Every ability the agent calls runs as a real WordPress user, with that user’s WordPress capabilities. You can choose between two authentication methods:

• OAuth 2.1 (recommended) — paste the URL into your agent, click Authorize in the browser consent screen, done. No credentials to copy.
• Application Password — for clients that don’t speak OAuth, or for scripted/automation use. Create a WordPress user, generate an Application Password, paste it into the agent’s config.

Both methods are supported simultaneously. You can mix and match per client.

HTTPS is mandatory for either method. Bearer tokens and Application Passwords are sent on every request — running this over plain HTTP would expose them in cleartext.

Get Your MCP Endpoint URL

The endpoint is always:

https://YOUR-SITE.com/wp-json/mcp/mcp-adapter-default-server

Replace YOUR-SITE.com with your actual domain. This is the URL you’ll paste into your agent regardless of which auth method you use.

Option A — Connect via OAuth (Recommended)

This is the fastest path and works with any modern OAuth-aware MCP client.

Step 1. In your AI client (Claude Desktop, ChatGPT, Cursor, etc.), open the MCP server / connector configuration and paste the endpoint URL above. The exact menu varies by client — for most it’s something like Settings → Connectors → Add or Settings → MCP Servers → Add.

Step 2. The client will respond with a browser pop-up showing the Maxi AI authorization page on your WordPress site. If you’re not already logged in to WordPress, log in as an administrator.

Step 3. Review what the agent is asking for and click Authorize.

Step 4. The browser closes and the client receives an access token automatically. You’re connected.

That’s it — no Application Password to copy anywhere.

Required role: by default, only users with the manage_options capability (Administrators) can authorize an OAuth client. The default can be changed in Settings → AI Connections → Settings.

Managing your OAuth connections

A new admin page lives at Settings → AI Connections with three tabs:

Option B — Connect via Application Password

Use this path if your client doesn’t support OAuth, or if you want a long-lived credential for a script or automation runtime.

Step 1 — Create a Dedicated WordPress User for the Agent

While not strictly required, the recommended practice is to give each agent its own WordPress user. This keeps the audit trail clean and lets you revoke a single agent without affecting your own login.

1. In wp-admin, go to Users → Add New User.
2. Fill in a username that makes the agent identifiable (e.g. agent-claude, agent-codex).
3. Set a strong password (you won’t use it for the MCP connection — you’ll generate a separate Application Password in the next step).
4. Choose a Role based on what the agent should be allowed to do:

For the full picture of what each role can do — and how the connection gate relates to it — see Manage Agent Users & Application Passwords.

PHP-enforced: content-mutating abilities (maxi/update-content, maxi/create-content, maxi/update-ai-settings, etc.) require Administrator. No rule or override can change this.

5. Click Add New User.

Step 2 — Generate an Application Password

1. Go to Users → All Users and click on the agent user you just created.
2. Scroll to the Application Passwords section.
3. Enter a name (e.g. claude-desktop) and click Add New Application Password.
4. WordPress will display the generated password once — copy it immediately. It will look like:

abcd EFGH 1234 ijkl MNOP 5678

Save it now — WordPress will not show it again. If you lose it, generate a new one and revoke the old.

Step 3 — Configure Your Agent

The exact configuration syntax depends on your MCP client. Below are examples for the most common ones.

All MCP clients connect to Maxi AI Core through the @automattic/mcp-wordpress-remote Node package, which wraps the WordPress MCP endpoint and handles authentication. You don’t need to install this package manually — npx will fetch it on first run.

The three values you’ll always provide are:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%Claudeclaude_desktop_config.json (Windows):

{
  "mcpServers": {
    "<yourwebsitename>": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "https://YOUR-SITE.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "<username>",
        "WP_API_PASSWORD": "<application-password>"
      }
    }
  }
}

Restart Claude Desktop after saving.

Codex

Codex uses the same wrapper, but you don’t need to edit a JSON file by hand. Open Codex and go to Settings → MCP Servers → Add Server, then enter:

• Command: npx
• Arguments: -y @automattic/mcp-wordpress-remote@latest
• Environment variables:
  • WP_API_URL = https://YOUR-SITE.com/wp-json/mcp/mcp-adapter-default-server
  • WP_API_USERNAME = your agent’s WordPress username
  • WP_API_PASSWORD = the Application Password from Step 2

Save and Codex will start the MCP server on next launch.

Other MCP Clients

Any MCP client that can spawn an npx command and pass environment variables can use the same @automattic/mcp-wordpress-remote wrapper. Provide the same three env vars (WP_API_URL, WP_API_USERNAME, WP_API_PASSWORD) in whatever format your client supports.

First Call: Bootstrap the Session

Once the agent is connected, the very first ability it should call is:

maxi/bootstrap-session

This is server-enforced — every other ability is blocked until bootstrap is acknowledged. It returns:

• The operational playbook — the rules the agent must follow.
• Active operator-notes — your authoritative instructions to the agent.
• Active knowledge-note headers — accumulated solutions from past sessions.
• Available reference docs the agent can fetch on demand.

Most agents will call this automatically on the first turn. You can verify by asking your agent:

“Connect to my site and tell me what version of Maxi AI Core is running.”

A correctly connected agent will bootstrap, then call maxi/get-site-info and report the version, license status, and entitlements.

Troubleshooting

Next Step

With your agent connected, proceed to Run Your First Operation.