WPBay’s MCP Server Documentation

1. What this server is

The Model Context Protocol (MCP) is an open standard for giving language models structured, tool-shaped access to external systems. The WPBay MCP server exposes the WPBay marketplace catalog as three MCP tools so an assistant can answer questions such as “is there already a WooCommerce subscription plugin that does X?” with real listings, prices, compatibility data and ratings rather than guesses.

Request path

A tool call travels through four hops. Nothing about your client, your prompt or your identity is stored along the way.

MCP client  (Claude, Cursor, your own agent)
    |  JSON-RPC 2.0 over Streamable HTTP
    v
https://mcp.wpbay.com/mcp
    |  stateless Node/TypeScript gateway
    |  validates input, bounds the request, validates the response
    v
https://wpbay.com/wp-json/wpbay-agent/v1/*
    |  the same query builder that powers the WPBay website search
    v
Public catalog projection  ->  structuredContent

The gateway is stateless: it keeps no sessions, no conversation history and no per-user storage. Each tool call is independent, and identical parameters produce identical results for the lifetime of the cache window.

Server instructions

MCP servers may send the client a short instruction string that the model sees alongside the tool list. WPBay sends this, verbatim:

2. Connect in one minute

Claude Code

claude mcp add --transport http wpbay https://mcp.wpbay.com/mcp

Claude Desktop, Cursor, and other JSON-configured clients

Add the server to your client’s MCP configuration file — claude_desktop_config.json for Claude Desktop, .cursor/mcp.json for Cursor, and the equivalent for other clients:

{
  "mcpServers": {
    "wpbay": {
      "type": "http",
      "url": "https://mcp.wpbay.com/mcp"
    }
  }
}

Restart the client after saving. Three tools should appear under the wpbay server.

MCP Inspector

To explore the schemas interactively before writing any code:

npx @modelcontextprotocol/inspector

Choose transport Streamable HTTP and enter https://mcp.wpbay.com/mcp.

Raw JSON-RPC

The endpoint speaks ordinary JSON-RPC 2.0, so you can drive it with curl while debugging:

# List the available tools
curl -sS https://mcp.wpbay.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call a tool
curl -sS https://mcp.wpbay.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
        "jsonrpc":"2.0","id":2,"method":"tools/call",
        "params":{
          "name":"search_wordpress_software",
          "arguments":{"query":"woocommerce subscriptions","per_page":3}
        }
      }'

Health check

For uptime monitoring, GET https://mcp.wpbay.com/healthz returns {"status":"ok"} with Cache-Control: no-store. It performs no upstream call and is not counted differently from any other request.

3. Capabilities and boundaries

Every tool carries the same MCP annotations, which clients can use to decide whether a call needs human approval:

What the server does

• Searches the public WPBay catalog by natural-language phrase and structured filters.
• Returns the authoritative public record for a known product ID.
• Compares two to five products across identical, normalized fields.

What the server does not do

• No accounts, carts, checkout or purchasing. There is no write path of any kind.
• No private data. Only published, non-password-protected products are visible. The projection is a subset of what an anonymous visitor can already read on wpbay.com.
• No contact details. Seller email addresses are never returned, and support is expressed as a category rather than an address.
• No licence keys, downloads or file contents. Documentation ZIPs are declared but never linked to a download URL.
• No link following. Seller-supplied preview, video and documentation URLs are returned exactly as stored and are never fetched by WPBay on your behalf.
• No personalisation. Responses depend only on the parameters you send.
• No HTML. Editorial text is converted to plain text with scripts, styles, tags and shortcodes removed before it is returned.

4. Tool: search_wordpress_software

Every parameter is optional. Calling the tool with an empty argument object returns the first page of the default catalog ordering. Unknown parameter names are rejected rather than ignored, so a typo fails loudly instead of silently widening your search.

Parameters

Example call

{
  "name": "search_wordpress_software",
  "arguments": {
    "query": "recurring payments for woocommerce",
    "product_types": ["plugin"],
    "compatible_with": ["woocommerce"],
    "minimum_rating": 4,
    "maintenance": "healthy",
    "sort": "best_selling",
    "per_page": 3
  }
}

Example response abbreviated

{
  "api_version": "1",
  "products": [
    {
      "id": 1842,
      "slug": "seo-sam",
      "title": "SEO Sam",
      "summary": "Automated on-page SEO auditing and fixes for WordPress.",
      "product_type": "plugin",
      "categories": ["SEO", "Marketing"],
      "tags": ["seo", "automation"],
      "seller": { "name": "MallorcaTech", "url": "https://wpbay.com/store/mallorcatech/" },
      "url": "https://wpbay.com/product/seo-sam/",
      "thumbnail_url": "https://wpbay.com/wp-content/uploads/seo-sam-300x300.png",
      "pricing": {
        "currency": "USD",
        "minimum_price": 39,
        "maximum_price": 149,
        "payment_models": [{ "key": "subscription_year", "label": "Yearly subscription" }],
        "license_sites": ["1 site", "5 sites", "Unlimited"]
      },
      "license": { "key": "split", "label": "Split licence" },
      "rating": { "average": 4.8, "count": 24 },
      "sales": 312,
      "compatibility": {
        "wordpress": ["6.6", "6.7", "6.8"],
        "php": ["8.1", "8.2", "8.3"],
        "integrations": ["WooCommerce", "Elementor"]
      },
      "updated_at": "2026-08-30T09:14:00+00:00",
      "product_health": { "available": true, "score": 92, "status": "excellent", "label": "Excellent" },
      "uses_wpbay_sdk": true
    }
  ],
  "pagination": { "page": 1, "per_page": 3, "total": 47, "total_pages": 16 }
}

5. Tool: get_wordpress_product

Parameters

This tool takes an ID, not a name. Resolve a product with search_wordpress_software first, then pass the id it returned. An ID that does not exist, or that points to a product which is not publicly listed, returns a not found tool error — the two cases are deliberately indistinguishable.

Example call

{
  "name": "get_wordpress_product",
  "arguments": { "product_id": 1842 }
}

The response is the full detail projection: every field from the search projection, plus the comparison fields, plus long description, pricing offers, previews, screenshots, changelog availability and — for service listings — the service breakdown.

6. Tool: compare_wordpress_products

Parameters

Duplicate IDs are rejected rather than de-duplicated. If any of the requested IDs is missing or not publicly listed, the whole call returns a not found error — a comparison is either complete or it is not returned, so a model can never silently compare four products while believing it compared five.

Example call

{
  "name": "compare_wordpress_products",
  "arguments": { "product_ids": [1842, 1907, 2033] }
}

Results are returned in the comparison projection, which is the search projection plus version, publication date, included files, support category, documentation availability and detailed Product Health with supporting facts.

7. Response field reference

All three tools return a structuredContent object validated against the output schema advertised in tools/list, plus a short human-readable content summary for clients that cannot consume structured output. Every response carries api_version: "1".

Base fields — present in all three projections

Comparison projection — additional fields

Detail projection — additional fields

Nested objects

pricing (summary — all projections)

pricing.offers[] (detail only)

pricing.offers[].billing

product_health

A discriminated union on available. When available is false, that is the only field present — do not expect a score.

service (detail, service listings only)

pagination (search only)

8. Value enumerations

9. Errors and retries

Tool-level errors

When a tool cannot complete, it returns a normal MCP result with isError: true and a single plain-text message. Messages are deliberately short and generic: they never contain upstream response bodies, stack traces, internal hostnames, credentials or request internals.

The gateway already retries once, internally, on a transient upstream failure (502, 503, 504, or a network fault) with a short randomised delay. By the time you see upstream_unavailable, one retry has already been spent.

HTTP-level errors

These are returned by the endpoint itself, before any tool runs.

Request correlation

Every response carries an X-Request-ID header. Send your own X-Request-ID (8–64 characters, alphanumeric plus . _ : -) and it will be echoed back and used in server-side logs; otherwise one is generated. Quote it when reporting a problem. W3C Trace Context headers (traceparent, tracestate, baggage) are propagated when supplied.

10. Rate limits

Limits are applied in a fixed 60-second window and are enforced on two axes at once: a ceiling for each individual JSON-RPC method, and a ceiling across all methods combined. The combined ceiling is what stops a client from exhausting one method and simply moving on to the next.

Clients are distinguished by a salted HMAC of the network address the request arrives from. The value is derived per request and never stored, logged in reversible form, or shared.

Exceeding any ceiling produces 429 with a Retry-After header giving whole seconds until the window resets. Honour it. Retrying before the window rolls over only consumes the next window’s budget.

11. Caching and freshness

Catalog responses are cached server-side and are also marked cacheable for intermediaries. Pricing, ratings and availability can therefore trail the website by up to the values below, which is normally invisible but matters if you are checking whether a sale has just started.

Product edits purge the affected cache entries immediately, so a corrected price generally appears well inside the published lifetime rather than at the end of it.

12. Direct REST API

The same catalog is available over plain HTTP for clients that do not speak MCP. It is public and read-only, requires no authentication, and carries the same data contract — the MCP gateway is a thin, schema-validating wrapper around exactly these three endpoints.

Base URL: https://wpbay.com/wp-json/wpbay-agent/v1/

Passing lists

Array parameters accept either repeated bracket syntax or a comma-separated string. These are equivalent:

GET /wp-json/wpbay-agent/v1/search?product_types[]=plugin&product_types[]=theme
GET /wp-json/wpbay-agent/v1/search?product_types=plugin,theme

GET /wp-json/wpbay-agent/v1/compare?ids[]=1842&ids[]=1907
GET /wp-json/wpbay-agent/v1/compare?ids=1842,1907

Over REST, product_types also accepts the plural spellings plugins, themes, scripts and services. The MCP tool accepts the singular forms only.

Example

curl -sS 'https://wpbay.com/wp-json/wpbay-agent/v1/search?query=seo&per_page=2&sort=top_rated'

Strict parameter handling

Unknown query parameters are rejected, not ignored. A misspelled filter returns 400 rather than quietly returning unfiltered results.

Error envelope

Errors use one stable shape across all three endpoints:

{
  "error": {
    "code": "rate_limited",
    "category": "rate_limited",
    "message": "Too many catalog requests. Try again later."
  },
  "request_id": "4f1c8a2e-...."
}

Response headers

Rate limits for direct REST access

Anonymous REST callers get a smaller budget than MCP clients, in the same fixed 60-second window:

13. Versioning and compatibility

Catalog contract

Every response carries api_version, currently "1". The contract is:

• New fields may be added at any time without a version bump. Parse defensively and ignore keys you do not recognise — the gateway itself tolerates unknown upstream fields rather than failing.
• Existing fields will not change type or meaning within a version.
• A breaking change bumps api_version. If you pin behaviour to anything, pin it to that value.

Input strictness

Tool inputs are the opposite: unknown keys are rejected. That asymmetry is deliberate. An unexpected key in a response is WPBay having shipped a new field; an unexpected key in a request is a caller mistake, and failing loudly is more useful than silently dropping the filter you thought you applied.

Protocol revisions

The endpoint negotiates the protocol revision during initialize and serves both the current MCP revision and the previous one, so older clients keep working without configuration. Use whichever your SDK defaults to.

14. Guidance for agent authors

• Search first, then fetch. get_wordpress_product and compare_wordpress_products take IDs, never names. Always resolve through search_wordpress_software.
• Prefer one comparison to three detail calls. compare_wordpress_products returns normalized fields for up to five products in a single request and is far cheaper against your budget.
• Raise per_page before raising page. One request for 20 results costs a twentieth of twenty requests for one.
• Read structuredContent, not the text summary. The content string exists only as a fallback for clients without structured output; it is a one-line gloss, not the data.
• Treat absent as absent. null prices, empty version strings and available: false health are normal for legitimate listings. Do not present them as zero, free, or unhealthy.
• Do not dereference returned URLs automatically. Preview, video and documentation links are seller-supplied and are not validated for content by WPBay.
• Present, do not embellish. Compatibility lists, ratings and Product Health are facts from the catalog. Capabilities not stated in the data should not be inferred from a product’s name or category.
• Respect Retry-After. It is an exact number of seconds, not a suggestion.

15. Running your own gateway

The hosted endpoint at mcp.wpbay.com is all most integrations need. The section below is for teams who want to run the gateway themselves — inside a private network, or against a staging catalog.

Operating the gateway: security model, environment variables and deployment

Security model

• The catalog is public. The gateway’s internal token changes rate-limit tiers; it does not unlock private data, and no configuration makes unpublished products visible.
• Client-supplied x-wpbay-mcp-token and x-wpbay-mcp-client headers are stripped on entry, so a caller cannot impersonate the gateway or claim a different client identity.
• Client identity is a salted HMAC of the remote address, never the address itself.
• Host and Origin are validated against an allow-list; anything else is refused with 403.
• Upstream calls are bounded on every axis: 8-second timeout, 1 MB maximum response, redirects refused outright, one retry on transient failure.
• Responses are validated against the published schemas before reaching a client, so a malformed upstream payload becomes a clean tool error rather than malformed structured output.
• Error text is fixed and generic — upstream bodies, tokens and internal hostnames are never echoed.

Environment variables

Variable	Default	Bounds and notes
WPBAY_API_BASE_URL	required	Absolute URL. No credentials, query string or fragment. Must be HTTPS when NODE_ENV=production.
WPBAY_MCP_INTERNAL_TOKEN	empty	≥ 32 characters in production, ≤ 512. Selects the trusted rate-limit tier upstream and salts the client fingerprint.
NODE_ENV	development	development, test or production.
WPBAY_MCP_HOST	127.0.0.1	Loopback only — 127.0.0.1, localhost or ::1. Put a reverse proxy in front; the process refuses to bind a public interface.
PORT	3000	1 – 65535.
WPBAY_MCP_ALLOWED_HOSTS	127.0.0.1, localhost, [::1], mcp.wpbay.com	Comma-separated, 1 – 20 hostnames.
WPBAY_MCP_ALLOWED_ORIGINS	same as above	Comma-separated, 1 – 20 hostnames.
WPBAY_MCP_BODY_LIMIT	64kb	Between 1kb and 1mb.
WPBAY_API_TIMEOUT_MS	8000	500 – 30,000 ms.
WPBAY_API_MAX_RESPONSE_BYTES	1048576	16 KB – 4 MB.
WPBAY_API_RETRY_BASE_DELAY_MS	100	0 – 1,000 ms; jittered.
WPBAY_MCP_RATE_LIMIT_WINDOW_MS	60000	1,000 ms – 1 hour.
WPBAY_MCP_RATE_LIMIT_CLIENT_MAX	120	Per client, per method. 1 – 100,000.
WPBAY_MCP_RATE_LIMIT_CLIENT_TOTAL_MAX	240	Per client, all methods. 1 – 100,000.
WPBAY_MCP_RATE_LIMIT_GLOBAL_MAX	5000	All clients, per method. 1 – 1,000,000.
WPBAY_MCP_RATE_LIMIT_GLOBAL_TOTAL_MAX	10000	All clients, all methods. 1 – 1,000,000.

Deployment notes

• Terminate TLS at a reverse proxy and forward to the loopback port. The process trusts proxy headers from loopback only.
• Run the service from outside the web root. Application source, node_modules and lockfiles should never be reachable over HTTP.
• Keep secrets out of wp-content. Supply them through the process environment or a systemd unit, not a file under a served directory.
• Point monitoring at /healthz and alert on non-200.
• The service is stateless, so it scales horizontally — but rate-limit counters are per process, so N instances means N times the published budget unless limits are divided accordingly.

WPBay MCP Server · Catalog API version 1 · Endpoint https://mcp.wpbay.com/mcp
Questions, an unexpected response, or a schema that does not match this page? Include the X-Request-ID from the response when you get in touch.