WP MCP Discovery

Make any WordPress site agent-discoverable. One toggle ships .well-known/mcp.json, a public MCP endpoint, an llms.txt index, and public-safe formatters for any post type.

Schema.org gets your site crawled. MCP gets it queried. SEO plugins handle the first; this plugin handles the second.

What it does

When enabled, this plugin serves three surfaces that close the agent-discovery loop:

For every post type you opt in, it auto-registers three MCP tools:

• list_<post_type> — paginated, search-aware list of public-safe summaries
• get_<post_type> — single post by id or slug, with full body
• search — cross-post-type search across opted-in content

The formatters are public-safe by default: only fields that are safe for unauthenticated consumers (title, slug, excerpt, url, taxonomies, featured image, dates, full content). The wall lives in the data source — the formatter never reads admin fields, so it can't leak them.

Why this matters

WordPress runs ~40% of the web. Its REST API ships with core. But no major SEO plugin (Yoast, Rank Math, AIOSEO) emits the MCP discovery layer in 2026. Agents that find your domain still have no path from "I know about this site" to "I have a structured catalog I can query." This plugin fills that gap.

Install

Until this is in the WordPress.org plugin directory, install from the GitHub release:

1. Download the latest release zip from the Releases page.
2. WordPress admin → Plugins → Add New → Upload Plugin → choose the zip.
3. Activate.
4. Settings → Agent Discovery → enable the master toggle, opt in the post types you want public, save.

Or via WP-CLI:

wp plugin install https://github.com/sethshoultes/wp-mcp-discovery/archive/main.zip --activate

Verify the loop

After enabling:

# 1. Discovery file is served
curl https://yoursite.com/.well-known/mcp.json

# 2. Service info from the endpoint
curl https://yoursite.com/wp-json/wp-mcp-discovery/v1/mcp

# 3. Tool catalog
curl -X POST https://yoursite.com/wp-json/wp-mcp-discovery/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 4. A real query
curl -X POST https://yoursite.com/wp-json/wp-mcp-discovery/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search","arguments":{"query":"hello world","limit":3}}}'

All four succeed without auth, or you haven't shipped.

Connect from an agent

Claude Code, Cursor, Codex (.mcp.json)

{
  "mcpServers": {
    "your-site": {
      "type": "http",
      "url": "https://yoursite.com/wp-json/wp-mcp-discovery/v1/mcp"
    }
  }
}

Claude.ai

Settings → Connectors → Add custom connector → paste the URL above. No auth required.

Per-post opt-out

Even when a post type is enabled, individual posts can be hidden via the Agent Discovery meta box on the post edit screen. The MCP tools will skip these posts.

Hooks for plugin developers

// Register a custom tool (e.g., from an LMS plugin)
add_filter('wp_mcp_discovery_register_tools', function($tools) {
    $tools['list_courses'] = [
        'description'  => 'List all published courses with metadata.',
        'input_schema' => ['type' => 'object', 'properties' => [...]],
        'handler'      => 'my_plugin_list_courses',
    ];
    return $tools;
});

// Enrich the formatter for a specific post type
add_filter('wp_mcp_discovery_formatter_post', function($post_data, $post) {
    $post_data['custom_field'] = get_post_meta($post->ID, 'public_meta_key', true);
    return $post_data;
}, 10, 2);

// Observe each tool invocation (for analytics, audit logs, etc.)
add_action('wp_mcp_discovery_tool_invoked', function($tool_name, $args, $result) {
    error_log("MCP: {$tool_name}");
}, 10, 3);

Compatibility

• SEO plugins (Yoast, Rank Math, AIOSEO): orthogonal. This plugin does not modify robots.txt, sitemaps, or schema.org JSON-LD.
• All in One SEO Pro v4.9.6.2+ specifically: AIOSEO ships its own llms.txt generator, and its handler registers earlier than ours, so AIOSEO's llms.txt is what gets served when both plugins are active. There is no conflict — AIOSEO ships the index layer (a markdown crawl summary), this plugin ships the query layer (.well-known/mcp.json + the MCP endpoint). Both run cleanly side by side.
• Other MCP plugins (e.g., MemberPress AI Foundation): mounts at its own REST namespace; both can run side-by-side.
• Caching plugins: the discovery file and llms.txt are stable. 5-minute edge cache is recommended and the plugin emits Cache-Control: public, max-age=300.

Deployed in the wild

adventurebuildr.com (2026-05-07) — twenty-eight tools auto-registered, including Posts, Pages, MemberPress courses/lessons, and eleven custom post types from the AdventureBuildr storytelling stack (iasb_character, iasb_location, iasb_vehicle, iasb_weapon, iasb_lore, iasb_organization, iasb_technology, etc.). Under five minutes from install to first successful tools/call. Verify the live discovery loop:

curl https://adventurebuildr.com/.well-known/mcp.json
curl https://adventurebuildr.com/wp-json/wp-mcp-discovery/v1/mcp
curl -X POST https://adventurebuildr.com/wp-json/wp-mcp-discovery/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Roadmap

• v0.1 (now) — public read-only. Posts, pages, custom public post types. Per-post opt-out. Per-IP rate limiting.
• v0.5 — Application Passwords support. Capability-gated tools/list (each user sees only what they can invoke).
• v1.0 — submitted to WordPress.org plugin directory.
• v1.5 — OAuth 2.0 + RFC 7591 dynamic client registration. Calibrated for AI client traffic shape.
• v2.0 — OpenAPI 3.x export of the same tool surface, usable directly as a ChatGPT Custom GPT Action.

Related learning

A full lesson on the discovery pattern this plugin implements lives at Claude Academy → Agent-Discoverable Surfaces.

License

GPL-2.0-or-later.