# MCP Client Setup Guide

This guide explains how to connect various MCP clients to your WordPress MCP server using different transport protocols and authentication methods.

## Overview

WordPress MCP supports two transport protocols:

-   **STDIO Transport**: Traditional transport via `mcp-wordpress-remote` proxy
-   **Streamable Transport**: Direct HTTP-based transport with JSON-RPC 2.0

## Authentication Methods

### OAuth 2.1 (Recommended — one-click connect)

-   The easiest way to connect: your AI client registers itself and you approve a consent screen — no tokens to copy.
-   Enable it under **Atlas AI Connector → MCP Auth → "Enable OAuth 2.1 connect for the MCP server"**.
-   Uses OAuth 2.1 with PKCE + Dynamic Client Registration. Each token maps to your WordPress user, and your role + the per-role Access Control decide what the connection can do.
-   Requires your site to be served over **HTTPS** for remote clients (Claude.ai, Claude Desktop, ChatGPT). Local/`http` sites can use the `mcp-remote` bridge below.

### JWT Tokens (advanced / headless)

-   Generate tokens from **MCP Auth → Authentication Tokens**.
-   Useful for CI or headless clients, or where OAuth is not available.
-   Sent as `Authorization: Bearer <token>`.

### Application Passwords (alternative)

-   WordPress built-in authentication method (Basic auth).
-   Works with the `mcp-wordpress-remote` proxy.
-   Generate from **Users → Profile → Application Passwords**.

## Client Configurations

### Connect via OAuth 2.1 (recommended)

Works with Claude.ai, Claude Desktop, ChatGPT, Cursor, and any client that supports remote OAuth MCP servers.

1. In WordPress admin, go to **Atlas AI Connector → MCP Auth** and turn on **"Enable OAuth 2.1 connect for the MCP server"**.
2. Copy your server URL: `{{your-website.com}}/wp-json/awfah_mcp/mcp`
3. In your client, add a **custom / remote connector** and paste that URL:
    - **Claude.ai / Claude Desktop:** Settings → Connectors → **Add custom connector** → paste the URL (requires HTTPS).
    - **ChatGPT:** Settings → Apps → Advanced → enable **Developer Mode**, then add the URL with **OAuth** (Plus/Pro/Business/Enterprise).
4. Your browser opens a consent screen — click **Allow**. The client registers itself automatically (Dynamic Client Registration); there are no tokens to copy.
5. Review or revoke connected clients under **MCP Auth → Connected clients**.

**Local / `http` sites** (no HTTPS) — bridge via `mcp-remote` in your client config:

```json
{
	"mcpServers": {
		"atlas-ai-connector": {
			"command": "npx",
			"args": [ "-y", "mcp-remote", "{{your-website.com}}/wp-json/awfah_mcp/mcp" ]
		}
	}
}
```

On Windows, set `"command": "cmd"` and prepend `"/c", "npx"` to the args. Add `--allow-http` only when the site is plain `http` on localhost.

> Note: OAuth requires a root-domain HTTPS install for remote clients. On a subdirectory install, use JWT or Application Passwords (below).

### Claude Code

#### Using HTTP Transport with JWT Token (Recommended)

Add your WordPress MCP server directly to Claude Code using the HTTP transport:

```bash
claude mcp add --transport http awfah {{your-website.com}}/wp-json/awfah_mcp/mcp/streamable --header "Authorization: Bearer your-jwt-token-here"
```

For more information about Claude Code MCP configuration, see the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).

### Claude Desktop

#### Using JWT Token with mcp-wordpress-remote (Recommended)

Add to your Claude Desktop `claude_desktop_config.json`:

```json
{
	"mcpServers": {
		"awfah": {
			"command": "npx",
			"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
			"env": {
				"WP_API_URL": "{{your-website.com}}/wp-json/awfah_mcp/mcp",
				"JWT_TOKEN": "your-jwt-token-here",
				"LOG_FILE": "optional-path-to-log-file"
			}
		}
	}
}
```

#### Using Application Password with mcp-wordpress-remote

```json
{
	"mcpServers": {
		"awfah": {
			"command": "npx",
			"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
			"env": {
				"WP_API_URL": "{{your-website.com}}/wp-json/awfah_mcp/mcp",
				"WP_API_USERNAME": "your-username",
				"WP_API_PASSWORD": "your-application-password",
				"LOG_FILE": "optional-full-path-to-log-file"
			}
		}
	}
}
```

### Cursor IDE

#### Using mcp-wordpress-remote proxy

Add to your Cursor MCP configuration file:

```json
{
	"mcpServers": {
		"awfah": {
			"command": "npx",
			"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
			"env": {
				"WP_API_URL": "{{your-website.com}}/wp-json/awfah_mcp/mcp",
				"JWT_TOKEN": "your-jwt-token-here",
				"LOG_FILE": "optional-full-path-to-log-file"
			}
		}
	}
}
```

### VS Code MCP Extension

#### Direct Streamable Transport (JWT Only)

Add to your VS Code MCP settings:

```json
{
	"servers": {
		"awfah": {
			"type": "http",
			"url": "{{your-website.com}}/wp-json/awfah_mcp/mcp/streamable",
			"headers": {
				"Authorization": "Bearer your-jwt-token-here"
			}
		}
	}
}
```

### MCP Inspector (Development/Testing)

#### Using JWT Token with proxy

```bash
npx @modelcontextprotocol/inspector \
  -e WP_API_URL={{your-website.com}}/wp-json/awfah_mcp/mcp \
  -e JWT_TOKEN=your-jwt-token-here \
  -e WOO_CUSTOMER_KEY=optional-woo-customer-key \
  -e WOO_CUSTOMER_SECRET=optional-woo-customer-secret \
  -e LOG_FILE="optional-full-path-to-log-file"
  npx @automattic/mcp-wordpress-remote@latest
```

#### Using Application Password with proxy

```bash
npx @modelcontextprotocol/inspector \
  -e WP_API_URL={{your-website.com}}/wp-json/awfah_mcp/mcp \
  -e WP_API_USERNAME=your-username \
  -e WP_API_PASSWORD=your-application-password \
  -e WOO_CUSTOMER_KEY=optional-woo-customer-key \
  -e WOO_CUSTOMER_SECRET=optional-woo-customer-secret \
  -e LOG_FILE="optional-full-path-to-log-file"
  npx @automattic/mcp-wordpress-remote@latest
```

## Transport Protocol Details

### STDIO Transport

-   **Endpoint**: `/wp-json/awfah_mcp/mcp`
-   **Format**: WordPress-style REST API
-   **Authentication**: JWT tokens OR Application passwords
-   **Use Case**: Legacy compatibility, works with most MCP clients
-   **Proxy Required**: Yes (`mcp-wordpress-remote`)

#### Advantages:

-   Compatible with all MCP clients
-   Supports both authentication methods
-   Enhanced features via proxy (WooCommerce, logging)

#### Example Tools Available:

-   `awfah-posts/wp-posts-search` - Retrieve WordPress posts
-   `awfah-posts/wp-add-post` - Create new posts
-   `awfah-posts/wp-update-post` - Update existing posts
-   `awfah-users/wp-users-search` - Get user information
-   And many more...

### Streamable Transport

-   **Endpoint**: `/wp-json/awfah_mcp/mcp/streamable`
-   **Format**: JSON-RPC 2.0 compliant
-   **Authentication**: JWT tokens only
-   **Use Case**: Modern AI clients, direct integration
-   **Proxy Required**: No

#### Advantages:

-   Direct connection (no proxy needed)
-   Standard JSON-RPC 2.0 protocol
-   Lower latency
-   Modern implementation

#### Example Methods:

-   `tools/list` - List available tools
-   `tools/call` - Execute a tool
-   `resources/list` - List available resources
-   `resources/read` - Read resource content
-   `prompts/list` - List available prompts
-   `prompts/get` - Get prompt template

## Local Development Setup

### WordPress Local Environment

```json
{
	"mcpServers": {
		"wordpress-local": {
			"command": "node",
			"args": [ "/path/to/mcp-wordpress-remote/dist/proxy.js" ],
			"env": {
				"WP_API_URL": "{{your-website.com}}/wp-json/awfah_mcp/mcp",
				"JWT_TOKEN": "your-local-jwt-token",
				"LOG_FILE": "/tmp/awfah-local.log"
			}
		}
	}
}
```

## Troubleshooting

### Common Issues

#### JWT Token Expired

-   Generate a new token from WordPress admin
-   Check token expiration time in settings
-   Ensure system clock is synchronized

#### Authentication Failed

-   Verify JWT token is correctly copied
-   Check application password format (username:password)
-   Ensure user has appropriate permissions

#### Connection Timeout

-   Verify WordPress site is accessible
-   Check firewall settings
-   Ensure proper SSL certificate if using HTTPS

#### Proxy Issues

-   Update mcp-wordpress-remote to latest version:
    ```bash
    npm install -g @automattic/mcp-wordpress-remote@latest
    ```
-   Check proxy logs for error details
-   Verify environment variables are set correctly

## Security Best Practices

1. **Use JWT tokens** instead of application passwords when possible
2. **Set shortest expiration time** needed for your use case (1-24 hours)
3. **Revoke unused tokens** promptly from the admin interface
4. **Never commit tokens** to version control systems
5. **Use HTTPS** for production environments
6. **Regularly rotate tokens**

## Support

For additional help:

-   Check the [Contact Us](https://atlasaidev.com/contact-us/)