WebMCP for WordPress — AI Agent Communication Protocol

Why This Matters

WebMCP (Web Model Context Protocol) is an emerging standard for AI-agent-to-website communication, based on Google Chrome’s MCP proposal. It gives AI agents a single, predictable URL to learn everything about your site — what it offers, what endpoints are available, and what content it serves.

Think of it as a service manifest. Before an agent browses your products or reads your content, it checks your WebMCP endpoint to understand the full picture. Citelayer® implements this as a .well-known endpoint, following the convention established by other web standards like robots.txt and security.txt.

How It Works

Citelayer registers a WordPress rewrite rule that maps the .well-known/mcp/context.json URL to a dynamic handler. When a request hits this URL, WordPress processes it internally and returns a JSON response with your site’s information, capabilities, and available endpoints.

• Endpoint: yoursite.com/.well-known/mcp/context.json
• Implemented via WordPress rewrite rule — no physical file needed
• Returns structured JSON with site info, capabilities, and endpoint URLs
• CORS-enabled for cross-origin access
• Cached with a 7-day transient for performance

Endpoint

GET /.well-known/mcp/context.json

Returns the full WebMCP context for your site. The response structure adapts based on whether WooCommerce is active.

Standard WordPress Response

On a regular WordPress site (without WooCommerce), you get a clean baseline response:

{
  "mcp_version": "1.0",
  "site": {
    "name": "Your Site Name",
    "description": "Your site tagline",
    "url": "https://yoursite.com",
    "type": "website",
    "platform": "WordPress"
  },
  "capabilities": [
    "llms_txt",
    "schema_org",
    "markdown"
  ],
  "endpoints": {
    "llms_txt": "/llms.txt",
    "schema": "/wp-json/citelayer/v1/schema"
  }
}

This tells AI agents that your site supports llms.txt, Schema.org structured data, and markdown content output. It also provides the endpoint URLs where agents can access each feature.

WooCommerce Response

When WooCommerce is active, the response expands significantly:

{
  "mcp_version": "1.0",
  "site": {
    "name": "Your Store Name",
    "description": "Your store tagline",
    "url": "https://yourstore.com",
    "type": "ecommerce",
    "platform": "WooCommerce"
  },
  "capabilities": [
    "llms_txt",
    "schema_org",
    "markdown",
    "product_catalog",
    "ucp_v1",
    "semantic_search",
    "cart_operations"
  ],
  "endpoints": {
    "llms_txt": "/llms.txt",
    "schema": "/wp-json/citelayer/v1/schema",
    "products": "/wp-json/citelayer/v1/products",
    "search": "/wp-json/citelayer/v1/search",
    "cart": "/wp-json/citelayer/v1/cart"
  },
  "content": {
    "languages": ["en"],
    "currency": "USD",
    "product_count": 142,
    "primary_categories": [
      "Electronics",
      "Clothing",
      "Home & Garden",
      "Sports",
      "Books"
    ]
  }
}

Key differences with WooCommerce:

• site.type changes from "website" to "ecommerce"
• site.platform changes from "WordPress" to "WooCommerce"
• capabilities gains four entries: product_catalog, ucp_v1, semantic_search, and cart_operations
• endpoints adds products, search, and cart URLs
• content object appears with your store’s languages, currency, total product count, and top 5 product categories

Response Headers

Every response includes these headers:

• X-Citelayer-Version — The installed plugin version
• Access-Control-Allow-Origin: * — Allows requests from any origin
• Cache-Control: public, max-age=604800 — Tells clients and CDNs to cache for 7 days
• Content-Type: application/json; charset=utf-8

Configuration

WebMCP is enabled by default. You control it through the Citelayer settings page or programmatically with a filter.

• Admin setting: Toggle WebMCP on or off in Citelayer → Settings
• Filter: citelayer_enable_webmcp — return false to disable
• Default: Enabled

When you disable WebMCP, Citelayer does not register any hooks or rewrite rules for this feature. This is a clean deactivation — no leftover routes, no error responses, no performance overhead.

// Disable WebMCP programmatically
add_filter( 'citelayer_enable_webmcp', '__return_false' );

Note: After enabling or disabling WebMCP, flush your permalink settings (Settings → Permalinks → Save Changes) to update the rewrite rules.

Verify It Works

After activating Citelayer, confirm that WebMCP is serving correctly.

In Your Browser

Visit https://yoursite.com/.well-known/mcp/context.json directly. You should see the JSON response with mcp_version, your site info, and the capabilities list.

With cURL

curl -s https://yoursite.com/.well-known/mcp/context.json | jq .

Check the response headers:

curl -I https://yoursite.com/.well-known/mcp/context.json

Look for X-Citelayer-Version, Access-Control-Allow-Origin: *, and Cache-Control: public, max-age=604800 in the output.

Troubleshooting

If you get a 404, flush your permalinks. Go to Settings → Permalinks and click Save Changes. This forces WordPress to regenerate rewrite rules, including the WebMCP route.

“WebMCP Endpoint Not Reachable”

Seeing this warning in your WordPress admin?

⚠️ WebMCP endpoint not reachable. The WebMCP endpoint at /.well-known/mcp/context.json is not accessible. If you are using Nginx, the server configuration must be adjusted. The endpoint is available as a fallback at ?citelayer_webmcp=1.

What’s happening: Nginx tries to locate /.well-known/mcp/context.json as a physical file on the server. When the file doesn’t exist, Nginx returns a 404 error—before WordPress even boots. The WebMCP plugin never gets a chance to handle the request.

The fix: You need to teach Nginx to pass all requests under /.well-known/mcp/ to WordPress, instead of looking for a physical file.

---

Nginx Configuration (Step-by-Step)

Add this location block to your Nginx configuration:

# Standard WordPress block (existing)
location / {
    try_files $uri $uri/ /index.php?$args;
}

# NEW: Explicitly pass .well-known to WordPress
location ~ ^/\.well-known/mcp/ {
    try_files $uri $uri/ /index.php?$args;
}

Where does this go?

• Self-managed servers: /etc/nginx/sites-available/your-domain.conf or /etc/nginx/nginx.conf
• Managed hosting: Contact your host or server admin—this cannot be changed through WordPress

After making changes:

# 1. Test configuration (important!)
sudo nginx -t

# 2. Reload Nginx (zero downtime)
sudo systemctl reload nginx

Note: If you already have a location ~ ^/\.well-known/ block (e.g., for Let’s Encrypt), add the MCP block inside or after it—or extend the existing block to include the rewrite.

---

Fallback Endpoint (Available Immediately)

If you don’t have direct server access or your host won’t modify the configuration: The fallback works always, without any rewrite rules.

URL:

https://your-domain.com/?citelayer_webmcp=1

This URL returns identical JSON to the standard endpoint. The only difference: It’s not available at the canonical path /.well-known/mcp/context.json.

When to use:

• Immediate test whether the plugin works at all
• Hosting environments without Nginx access
• Temporary solution until your server admin updates the rewrite rules

---

Testing Methods

Verify your configuration (or diagnose issues) with these three tests:

1. Browser Test (Standard Endpoint)

https://your-domain.com/.well-known/mcp/context.json

Expected result: JSON output with mcpVersion, endpoints, authentication—no 404, no redirect to homepage.

2. Browser Test (Fallback Endpoint)

https://your-domain.com/?citelayer_webmcp=1

Expected result: Identical JSON to Test 1—confirms the plugin is working.

3. Terminal Test (HTTP Status)

curl -I https://your-domain.com/.well-known/mcp/context.json

Expected result: HTTP/2 200 (or HTTP/1.1 200)

---

Common Errors

Error	Cause	Solution
404 Not Found	Nginx not passing to WordPress	Add location block for /.well-known/mcp/
403 Forbidden	Nginx blocking hidden directories (. prefix)	Explicit location rule to allow .well-known
Blank page	PHP error or plugin inactive	Check WordPress error log, verify plugin status
Redirect to homepage	Rewrite rule missing or misplaced	Insert location block after standard WordPress block
JSON offered as download	Missing Content-Type header	Normal—curl/browser still display correctly

---

Hosting-Specific Notes

Shared Hosting (All-Inkl, HostEurope, etc.):

• Nginx configuration usually not directly editable
• Use fallback endpoint ?citelayer_webmcp=1
• Or: Contact support with the location block template above

Cloud Hosting (AWS, GCP, Azure):

• Check load balancer or reverse proxy settings
• May need additional rewrite rules in cloud configuration

WordPress Managed Hosting (Raidboxes, Kinsta, WP Engine):

• Contact support—this is standard for enterprise plugins
• Often pre-configured; 404 usually indicates caching layer

Docker/Containers:

• Modify Nginx config in container or mount as volume
• For docker-compose: Config change requires docker-compose restart

---

Still Having Issues?

If all tests fail:

1. Check plugin status: Is Citelayer WebMCP activated?
2. Flush permalinks: WordPress Admin → Settings → Permalinks → “Save Changes”
3. Clear caches: Object cache, page cache, CDN cache (Cloudflare, etc.)
4. Enable debug log: wp-config.php → define('WP_DEBUG_LOG', true);
5. Check server logs: /var/log/nginx/error.log or hosting panel

The fallback endpoint ?citelayer_webmcp=1 is your fastest diagnostic: If that works, the problem is definitely in your Nginx rewrite configuration—not the plugin.

Technical Details

Caching

The WebMCP response is cached as a WordPress transient named citelayer_webmcp_context with a 7-day TTL. This keeps the endpoint fast even on high-traffic sites.

The cache is automatically invalidated when:

• A WooCommerce product is created, updated, or deleted
• The blogname option changes (site title)
• The blogdescription option changes (site tagline)
• The woocommerce_currency option changes

You do not need to manually clear the cache. Citelayer hooks into these events and deletes the transient automatically.

Rewrite Rule

Citelayer adds a rewrite rule that maps the .well-known URL to WordPress’s internal routing:

^.well-known/mcp/context.json$ → index.php?citelayer_webmcp=1

This means WordPress handles the request through its standard query system. No .htaccess edits, no Nginx location blocks — it works out of the box on any WordPress host.

Language Detection

The content.languages array in the WooCommerce response detects your site’s configured languages. Citelayer supports two multilingual plugins:

• WPML — Uses icl_get_languages() to list active languages
• Polylang — Uses pll_languages_list() to list active languages

If neither plugin is active, the languages array contains the site’s default locale.

Customizing the Response

Use the citelayer_webmcp_context filter to modify the full context object before it is cached and served.

add_filter( 'citelayer_webmcp_context', function( $context ) {
    // Add a custom capability
    $context['capabilities'][] = 'custom_api';

    // Add a custom endpoint
    $context['endpoints']['custom'] = '/wp-json/myplugin/v1/data';

    // Add contact information
    $context['site']['support_email'] = 'help@yoursite.com';

    return $context;
} );

Since the filter runs before caching, your modifications are stored in the transient and served on subsequent requests without re-running the filter. When the cache invalidates (product update, settings change), the filter runs again with fresh data.

CORS and Cache Headers

The endpoint sends Access-Control-Allow-Origin: * to allow access from any domain. This is required for AI agents that make cross-origin requests from browser-based environments. The Cache-Control: public, max-age=604800 header tells CDNs and browsers to cache the response for 7 days, matching the server-side transient TTL.

Related

• UCP Discovery — A complementary discovery protocol via REST API, focused on capability flags
• Schema.org Structured Data — Machine-readable product and organization data referenced in WebMCP capabilities
• Hooks & Filters — All available filters including citelayer_webmcp_context and citelayer_enable_webmcp
• llms.txt — The text-based site manifest referenced in WebMCP’s endpoint list