Commit 5b5d8256e58 for woocommerce
commit 5b5d8256e58003ebe547afec2959284b29e1ecfe
Author: Brian Coords <bacoords@gmail.com>
Date: Mon Aug 24 13:51:08 2026 -0700
Docs: Update MCP connection and authentication documentation (#67583)
* Update MCP connection documentation
* Update MCP authentication troubleshooting
* reference the specific mcp repo name
* remove unnecessary curl testing instructions
diff --git a/docs/features/mcp/README.md b/docs/features/mcp/README.md
index 04e78f2cae3..e2ff27b8637 100644
--- a/docs/features/mcp/README.md
+++ b/docs/features/mcp/README.md
@@ -155,100 +155,137 @@ wp option update woocommerce_feature_mcp_integration_enabled yes
## Authentication and Security
-### API Key Requirements
+### WordPress Application Password Requirements
-The deprecated WooCommerce MCP endpoint authenticates using WooCommerce REST API keys in the `X-MCP-API-Key` header:
+Remote HTTP connections authenticate using a WordPress username and an [Application Password](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/#basic-authentication-with-application-passwords). Do not use your account password or a WooCommerce REST API key.
-```http
-X-MCP-API-Key: ck_your_consumer_key:cs_your_consumer_secret
-```
+To create an Application Password:
-To create API keys:
+1. In the WordPress dashboard, navigate to **Users → Profile**.
+2. Under **Application Passwords**, enter a name for the MCP client.
+3. Click **Add New Application Password**.
+4. Copy the generated password and store it securely. WordPress only displays it once.
-1. Navigate to **WooCommerce → Settings → Advanced → REST API**
-2. Click **Add Key**
-3. Set appropriate permissions (`read`, `write`, or `read_write`)
-4. Generate and securely store the consumer key and secret
+Use the WordPress username and generated password as `WP_API_USERNAME` and `WP_API_PASSWORD` in the remote proxy configuration. Application Passwords can be revoked independently from the user's profile.
### HTTPS Enforcement
-Requests to the deprecated WooCommerce MCP endpoint require HTTPS by default. For local development, you can disable this requirement:
-
-```php
-add_filter( 'woocommerce_mcp_allow_insecure_transport', '__return_true' );
-```
+Use HTTPS for remote HTTP connections so credentials are encrypted in transit. Local STDIO connections authenticate through WP-CLI using the configured `--user` and do not require an Application Password.
### Permission Validation
-For the deprecated WooCommerce MCP endpoint, the transport layer validates operations against API key permissions:
-
-- `read` permissions: Allow GET requests
-- `write` permissions: Allow POST, PUT, PATCH, DELETE requests
-- `read_write` permissions: Allow all operations
+The MCP Adapter authenticates requests as the WordPress user associated with the Application Password. The default server requires an authenticated user with the `read` capability, and each WooCommerce ability also enforces its own permission callback. Use a dedicated WordPress user with only the capabilities the MCP client needs.
## Server Endpoint
-The deprecated WooCommerce MCP server is available at:
+WooCommerce abilities are available through the WordPress MCP Adapter's default server:
```text
-https://yourstore.com/wp-json/woocommerce/mcp
+https://yourstore.com/wp-json/mcp/mcp-adapter-default-server
```
+The WooCommerce-specific `/wp-json/woocommerce/mcp` endpoint is deprecated and should not be used for new integrations.
+
## Connecting to the MCP Server
-The examples below configure clients to use the deprecated WooCommerce MCP endpoint.
+Choose a connection method based on where the WordPress site is running. For a detailed overview and application-specific instructions, see [Connecting AI applications](https://developer.wordpress.org/news/2026/02/from-abilities-to-ai-agents-introducing-the-wordpress-mcp-adapter/#connecting-ai-applications) and the [wordpress/mcp-adaptor repository](https://github.com/wordpress/mcp-adapter).
-### Proxy Architecture
+### Local Sites Using STDIO
-The current MCP implementation uses a **local proxy approach** to connect MCP clients with WordPress servers:
+For a local WordPress installation, MCP clients can connect directly through the MCP Adapter's WP-CLI command. The client needs access to the WordPress files and a working WP-CLI installation.
-- **MCP Clients** (like Claude Code) communicate using the MCP protocol over stdio/JSON-RPC
-- **Local Proxy** (`@automattic/mcp-wordpress-remote`) runs on your machine and translates MCP protocol messages to HTTP requests
-- **WordPress MCP Server** receives HTTP requests and processes them through the WordPress Abilities system
+#### JSON Configuration
-This proxy pattern is commonly used in MCP integrations to bridge protocol differences and handle authentication. The `mcp-wordpress-remote` package acts as a protocol translator, converting the stdio-based MCP communication that clients expect into the HTTP REST API calls that WordPress understands.
+Add the following server to your MCP client configuration. Replace the WordPress path and user with values from your local environment:
-**Future Evolution**: While this proxy approach provides a robust foundation, future implementations may explore direct MCP protocol support within WordPress or alternative connection methods as the MCP ecosystem evolves.
+```json
+{
+ "mcpServers": {
+ "woocommerce_store": {
+ "command": "wp",
+ "args": [
+ "--path=/path/to/your/wordpress/site",
+ "mcp-adapter",
+ "serve",
+ "--server=mcp-adapter-default-server",
+ "--user=admin"
+ ]
+ }
+ }
+}
+```
-### Claude Code Integration
+Claude Desktop, Claude Code, and Cursor use the `mcpServers` property shown above. For VS Code, use `servers` instead.
-To connect Claude Code to your WooCommerce MCP server:
+#### Command-Line Configuration
-1. Go to **WooCommerce → Settings → Advanced → REST API**
-2. Create a new API key with "Read/Write" permissions
-3. Configure MCP with your API key using Claude Code:
+Claude Code users can add the same server from the command line:
```bash
-claude mcp add woocommerce_mcp \
- --env WP_API_URL=https://yourstore.com/wp-json/woocommerce/mcp \
- --env CUSTOM_HEADERS='{"X-MCP-API-Key": "YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET"}' \
- -- npx -y @automattic/mcp-wordpress-remote@latest
+claude mcp add woocommerce_store -- \
+ wp --path=/path/to/your/wordpress/site \
+ mcp-adapter serve \
+ --server=mcp-adapter-default-server \
+ --user=admin
```
-### Manual MCP Client Configuration
+You can verify the server directly with WP-CLI:
-For other MCP clients, add this configuration to your MCP settings. This configuration tells the MCP client to run the `mcp-wordpress-remote` proxy locally, which will handle the communication with your WordPress server:
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
+ wp --path=/path/to/your/wordpress/site \
+ mcp-adapter serve \
+ --server=mcp-adapter-default-server \
+ --user=admin
+```
+
+### Remote Sites Using HTTP
+
+For a remote WordPress installation, use the `@automattic/mcp-wordpress-remote` proxy. The proxy translates the MCP client's local STDIO messages into HTTP requests to the WordPress MCP Adapter.
+
+Before connecting:
+
+1. Create or select a dedicated WordPress user with the minimum required capabilities.
+2. Open the user's **Profile** screen and create a WordPress Application Password.
+3. Confirm the site uses HTTPS and non-Plain permalinks.
+
+#### JSON Configuration
+
+Add the following server to your MCP client configuration. Replace the example URL, username, and Application Password:
```json
{
"mcpServers": {
- "woocommerce_mcp": {
- "type": "stdio",
+ "woocommerce_store": {
"command": "npx",
"args": [
"-y",
"@automattic/mcp-wordpress-remote@latest"
],
"env": {
- "WP_API_URL": "https://yourstore.com/wp-json/woocommerce/mcp",
- "CUSTOM_HEADERS": "{\"X-MCP-API-Key\": \"YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET\"}"
+ "WP_API_URL": "https://yourstore.com/wp-json/mcp/mcp-adapter-default-server",
+ "WP_API_USERNAME": "your-username",
+ "WP_API_PASSWORD": "your-application-password"
}
}
}
}
```
-**Important**: Replace `YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET` with your actual WooCommerce API credentials.
+Claude Desktop, Claude Code, and Cursor use the `mcpServers` property shown above. For VS Code, use `servers` instead. Do not commit a configuration containing an Application Password to version control.
+
+#### Command-Line Configuration
+
+Claude Code users can add the remote server from the command line:
+
+```bash
+claude mcp add \
+ --env WP_API_URL=https://yourstore.com/wp-json/mcp/mcp-adapter-default-server \
+ --env WP_API_USERNAME=your-username \
+ --env WP_API_PASSWORD='your-application-password' \
+ woocommerce_store \
+ -- npx -y @automattic/mcp-wordpress-remote@latest
+```
**Troubleshooting**: For common setup issues with npx versions or SSL in local environments, see the [mcp-wordpress-remote troubleshooting guide](https://github.com/Automattic/mcp-wordpress-remote/blob/trunk/Docs/troubleshooting.md).
@@ -376,9 +413,10 @@ The demo plugin creates a `woocommerce-demo/store-info` ability that retrieves s
## Authentication Failures
-- Confirm API key format: `consumer_key:consumer_secret`
-- Verify API key permissions match operation requirements
-- Ensure HTTPS is used or explicitly allowed for development
+- Confirm `WP_API_USERNAME` matches the WordPress user that created the Application Password
+- Confirm `WP_API_PASSWORD` contains an active Application Password, not the user's account password or a WooCommerce REST API key
+- Verify the WordPress user has the capabilities required by the ability
+- Ensure HTTPS is used for remote HTTP connections
## Ability Not Found