Skip to content
Protocols

Universal Context Protocol (UCP) for WordPress

5 min read


Why This Matters

Before an AI agent can interact with your site, it needs to know what your site can do. Can it browse products? Add items to a cart? Process a checkout? Without answers to these questions, agents either guess (and break things) or skip your site entirely.

UCP Discovery solves this with a single, machine-readable endpoint. Think of it as a business card for AI — one request tells an agent everything it needs to know about your site’s capabilities, platform, and version. No authentication required, no complex handshake. Just a clean JSON response that says “here’s what I can do.”

How It Works

Citelayer registers a public REST API endpoint that responds to capability discovery requests. When an AI agent sends a GET request to this endpoint, it receives a structured JSON object describing your site’s identity, platform, and supported operations.

  • REST API endpoint: GET /wp-json/citelayer/v1/ucp/discovery
  • Public — no authentication required
  • Rate limited to 60 requests per minute per IP address
  • Rate limiting uses WordPress transients with an IP hash key
  • CORS-enabled for cross-origin access from any domain

The endpoint is designed to be lightweight and fast. Agents hit it once to understand your site, then proceed to use the specific capabilities your site supports.

Endpoint

GET /wp-json/citelayer/v1/ucp/discovery

Returns the full UCP discovery manifest for your site. Here is the complete response structure:

{
  "protocol": "ucp",
  "version": "1.0",
  "shop": {
    "name": "Your Site Name",
    "url": "https://yoursite.com",
    "platform": "WooCommerce",
    "citelayer_version": "0.3.1"
  },
  "capabilities": {
    "product_browsing": false,
    "cart": false,
    "checkout": false
  },
  "upgrade": {
    "message": "Full UCP support available with Citelayer Premium",
    "url": "https://citelayer.ai/woocommerce-premium"
  }
}

Key details about the response:

  • protocol — Always "ucp". Identifies this as a Universal Context Protocol response.
  • version — The UCP specification version. Currently "1.0".
  • shop.name — Your WordPress site title, pulled from Settings → General.
  • shop.url — Your site’s home URL.
  • shop.platform — Always reports "WooCommerce" in the current version.
  • shop.citelayer_version — The installed Citelayer plugin version.
  • capabilities — Indicates which operations the site supports. In the free version, all capabilities return false.
  • upgrade — Present in the free version. Points agents (and developers) to Citelayer Premium for full UCP support.

Response Headers

Every response includes these headers:

  • X-Citelayer-Version — The installed plugin version
  • Access-Control-Allow-Origin: * — Allows cross-origin requests from any domain
  • Access-Control-Allow-Methods: GET, OPTIONS — Supports GET requests and CORS preflight

HTTP Status Codes

  • 200 — Success. Returns the discovery JSON.
  • 429 — Rate limit exceeded. The client has sent more than 60 requests in the last minute.
  • 503 — UCP Discovery is disabled in the admin settings.

Configuration

UCP Discovery is enabled by default. You control it through the Citelayer settings page in your WordPress admin.

  • Option name: citelayer_enable_ucp_discovery
  • Default: Enabled
  • Location: Citelayer → Settings in your WordPress admin

When you disable UCP Discovery, the endpoint returns a 503 Service Unavailable response. This cleanly signals to AI agents that the feature is not available, rather than returning an error or empty response.

Rate Limiting

The endpoint enforces a rate limit of 60 requests per minute per IP address. This protects your server from excessive polling while still allowing legitimate discovery requests. The rate limiter uses WordPress transients with a 60-second TTL, keyed by an IP hash.

IP detection is proxy-aware. Citelayer checks the following headers in order:

  1. CF-Connecting-IP (Cloudflare)
  2. X-Forwarded-For (reverse proxies, load balancers)
  3. X-Real-IP (Nginx)
  4. REMOTE_ADDR (fallback)

This ensures accurate rate limiting even when your site sits behind Cloudflare, a CDN, or a reverse proxy.

Verify It Works

After activating Citelayer, verify that UCP Discovery is running:

In Your Browser

Visit https://yoursite.com/wp-json/citelayer/v1/ucp/discovery directly. You should see the JSON response with your site name, URL, and capability flags.

With cURL

curl -s https://yoursite.com/wp-json/citelayer/v1/ucp/discovery | jq .

Check for the X-Citelayer-Version header:

curl -I https://yoursite.com/wp-json/citelayer/v1/ucp/discovery

You should see X-Citelayer-Version: 0.3.1 (or your installed version) in the response headers.

Technical Details

Customizing the Response

Use the citelayer_ucp_discovery_response filter to modify the discovery response before it is sent. This lets you add custom capabilities, change metadata, or inject additional information.

add_filter( 'citelayer_ucp_discovery_response', function( $response ) {
    // Add a custom capability
    $response['capabilities']['custom_search'] = true;

    // Add contact information
    $response['shop']['contact'] = 'support@yoursite.com';

    return $response;
} );

The filter receives the complete response array and must return the modified array. Your changes appear in the JSON output immediately — no cache to clear.

CORS Support

The endpoint sends permissive CORS headers to ensure AI agents can access it from any origin:

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: GET, OPTIONS

This is intentional. UCP Discovery is a public endpoint designed for broad access. Restricting origins would defeat its purpose as a universal discovery mechanism.

Free vs Premium

In the free version, all capabilities return false and the response includes an upgrade object. This tells AI agents that your site uses the UCP protocol but doesn’t yet support interactive operations like product browsing or cart management. Upgrading to Citelayer Premium enables full UCP support with active capabilities.

  • WebMCP — Another discovery protocol supported by Citelayer, using a .well-known endpoint
  • Markdown Content API — Serve your content in markdown format for AI consumption
  • REST API Reference — Full list of Citelayer REST API endpoints
  • Hooks & Filters — All available filters including citelayer_ucp_discovery_response