Documentation

Documentation

Installation

  1. Upload the plugin zip via Plugins → Add New → Upload Plugin.
  2. Activate it. A unique 256-bit API key is generated automatically.
  3. Open Dashboard → MCP to see your key and endpoint.

Connecting a client

The settings screen renders a ready-made config block. Copy it into your MCP client:

.mcp.json
{
  "mcpServers": {
    "my-site": {
      "type": "http",
      "url": "https://example.com/wp-json/custom-mcp/v1/mcp",
      "headers": { "x-custom-mcp-api-key": "your-key-here" }
    }
  }
}

The key travels in the x-custom-mcp-api-key header and is compared in constant time. Requests without a valid key are rejected with a 401.


Connect your editor

Step-by-step setup guides with the exact config file and shape for each client:


Tool reference

Site and options

  • wp_get_site_info — name, URL, version, active theme, detected builders, enabled write roots
  • wp_get_option / wp_update_option — read and write any option
  • wp_get_theme_mods / wp_update_theme_mod — Customizer settings
  • wp_get_custom_css / wp_update_custom_css — the active theme’s custom CSS

Content

  • wp_get_posts / wp_get_post — list and read any post type
  • wp_get_post_types — every registered post type on the site
  • wp_create_post / wp_update_post / wp_delete_post
  • wp_get_post_meta / wp_update_post_meta / wp_delete_post_meta
  • wp_upload_media / wp_get_media — media library

Taxonomies

  • wp_get_taxonomies — what a post type supports (category and post_tag for posts, product_cat and product_tag for WooCommerce products)
  • wp_get_terms — existing terms with id, slug, parent and post count
  • wp_set_post_terms — assign terms by name or id, replacing or appending; names that do not exist yet are created
  • wp_delete_term — remove a term

Page builders

  • wp_get_builder_data — detect the builder and return the decoded layout, its storage location and encoding
  • wp_update_builder_data — write a layout back, re-encoded the way that builder stores it, running its cache invalidation

Both accept an explicit meta_key, so a builder the plugin has never seen still works.

Filesystem

  • wp_list_files / wp_read_file / wp_write_file / wp_delete_file — scoped to an enabled root
  • wp_list_plugins / wp_set_plugin_active
  • wp_list_themes

Roots are plugins, themes, mu-plugins and uploads, each toggled independently in settings. Writes are restricted to php, js, css, json, txt, md, svg, html, htm, xml, csv, po, pot and mo.


Extending

Register a builder the plugin does not know about:

functions.php
add_filter( 'custom_mcp_builders', function ( $builders ) {
    $builders['my-builder'] = array(
        'label'      => 'My Builder',
        'store'      => 'meta',
        'meta_key'   => '_my_builder_data',
        'after_save' => 'my_builder_flush_cache',
    );
    return $builders;
} );

Add your own tools with custom_mcp_tools to advertise them and custom_mcp_execute_tool to handle the call. Return anything non-null to claim it.


Security notes

  • Read-only out of the box. Every write root is disabled on a fresh install — the connector cannot create or modify a single file until you switch one on.
  • Keys are unique per install and generated on activation — no shared default ships.
  • The endpoint fails closed: with no key configured every request is rejected, and both the JSON-RPC and streaming routes require the key.
  • The API cannot widen its own access. Write roots, the IP allowlist and the key itself are changeable only in wp-admin, so a leaked key cannot be used to turn on file writing or silently rotate the key.
  • Repeated invalid keys from one address are rate-limited; a valid key is never locked out.
  • Every write is recorded in an audit log in Dashboard → MCP, with the tool, target and source address, plus last-connection and last-rejected-key times.
  • An optional IP allowlist restricts which addresses may call the endpoint. Behind some proxies the server sees a different address, so test before relying on it.
  • Enabling a write root lets the MCP place executable PHP on your server. Treat the API key as a server credential and turn write roots off when you are not actively building.