How clients discover tools and resources

Discovery happens in two stages: finding out how to authenticate, then finding out what is available. A compatible client does both without configuration beyond the server URL.

Stage one: how to authenticate

1. The client calls the MCP endpoint without credentials.
2. The server answers 401 with a WWW-Authenticate header naming the protected resource metadata URL.
3. The client reads that document, which identifies the resource and names this site as its authorization server.
4. The client reads the authorization server metadata, which lists the registration, authorization and token endpoints, the supported grants and the available scopes.
5. The client registers itself and completes the OAuth flow.

This is why you only ever give a client the MCP URL. Everything else is advertised.

See Protected resource metadata and Authorization server metadata.

The WWW-Authenticate header is only sent when OAuth is enabled. With OAuth disabled, an unauthenticated request still returns 401 but without the pointer, so a client cannot bootstrap — expected, since API key mode requires manual configuration.

Stage two: what is available

Once authenticated, the client calls initialize and receives the negotiated protocol version, the server name from your Server label setting, and the capabilities the server advertises: tools, resources and prompts.

It then lists them:

What the tool list reflects

The list is built from what is registered on this site, which depends on which products are active. It does not vary by token.

That distinction matters when diagnosing:

• A tool is missing entirely — its product is not active here. WooCommerce tools need WooCommerce; POM Theme tools need the POM theme.
• A tool is listed but refuses to run — a scope, capability, gate or schema check rejected the call.

So a client can see a tool it is not allowed to use. Listing is discovery, not authorization. See MCP security model.

Input schemas

Each tool advertises a JSON schema for its arguments. Clients use it to construct valid calls, and the server enforces required arguments before running anything.

A well-behaved client will not send a call missing a required argument, because the schema told it what is needed. pom_ai_mcp_missing_argument usually means the client ignored the schema or the assistant improvised.

Resources and prompts

Resources are readable items addressed by URI, listed with resources/list and fetched with resources/read. See MCP resources.

Prompts are ready-made instructions the server publishes for common jobs — building a landing page, updating a builder page without breaking its structure, creating a content model, creating templates. prompts/list shows them and prompts/get returns one with arguments applied.

Prompts are filtered by what the caller may use: each declares the scopes and capability it needs, so a client only sees the ones it could actually run. Starting from a published prompt is more reliable than describing the same job from scratch. See Prompt recipes.

Rate limits during discovery

Listing calls count against the read limit like any other request. A client that re-lists aggressively can rate-limit itself; well-behaved clients list once per session and cache.

When discovery fails

Run the diagnostics from the MCP settings panel first. It fetches both metadata documents and the status endpoint from the server itself and reports the content type, whether the body parsed as JSON, and whether HTML appeared — which distinguishes a configuration problem from a client problem in one step.