Get the plugin
WP MCP/Guides/Guide

By · Published

How to build an MCP server, with a WordPress route

Building an MCP server is less work than it sounds, because the protocol is small. A server answers a handful of JSON-RPC messages: say hello, list the tools, run a tool. This guide shows those messages with curl so you can see what an SDK does for you, builds a minimal server, and then takes the WordPress route, where you register a function and let WordPress expose it. For background on the protocol, read what an MCP server is.

What you are building

An MCP server offers capabilities to a client such as Claude Code or Cursor. The main kind of capability is a tool: a named action with a description and a JSON Schema for its input. The model reads the description, decides when the tool fits, and sends arguments that match the schema.

Two transports are in common use:

  • stdio: the client starts your server as a local process and exchanges messages on standard input and output.
  • Streamable HTTP: your server sits at a URL and receives each message as an HTTP POST. This is the route for anything remote, including a website.

The messages are the same on both. For the trade-offs, see MCP vs API.

The handshake, with curl

Assume a server at https://example.com/mcp. Every message is JSON-RPC 2.0. First the client starts a session:

curl -s https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "0.1" }
    }
  }'

The server replies with its own protocol version, its capabilities (for example tools) and its name. If the reply carries an MCP-Session-Id header, send it back on every later request, along with an MCP-Protocol-Version header set to the negotiated version. The client then sends an initialized notification, which the server answers with 202 Accepted and no body, and asks what tools exist:

curl -s https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{ "jsonrpc": "2.0", "method": "notifications/initialized" }'

curl -s https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Add -H "MCP-Session-Id: ..." to both if the server issued one. The reply to a request can be plain JSON or an event stream, so a client has to handle both. The transport specification has the exact rules.

A tool entry looks like this:

{
  "name": "count-drafts",
  "description": "Returns the number of draft posts.",
  "inputSchema": { "type": "object", "properties": {} }
}

Finally a call:

curl -s https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": { "name": "count-drafts", "arguments": {} }
  }'

The result carries a content array, for example [{ "type": "text", "text": "7" }]. The sketch above follows the 2025-11-25 revision. Newer revisions change parts of the handshake, so check the specification for the revision you target.

That is the whole core. An SDK wraps it so you write only the tools.

A minimal server in Node

With the official TypeScript SDK a stdio server is short. This follows the current README of the TypeScript SDK, which installs @modelcontextprotocol/server. Earlier releases shipped as @modelcontextprotocol/sdk with different import paths, so match the code to the version you install and check its README:

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({ name: "demo", version: "0.1.0" });

server.registerTool(
  "add",
  {
    description: "Add two numbers.",
    inputSchema: z.object({ a: z.number(), b: z.number() })
  },
  async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] })
);

await server.connect(new StdioServerTransport());

Register it in a client and test it. In Claude Code, the steps are in Add an MCP server to Claude Code.

Design tips that matter more than the code

  • Write descriptions for the model. The description is the only thing deciding when a tool is chosen. Say what it does and when not to use it.
  • Keep schemas tight. Use enums and required fields. A loose schema invites bad arguments.
  • Return small results. Large payloads cost tokens on every turn. Paginate.
  • Separate reads from writes. Make writes explicit, and think about how a mistake is undone before you ship.
  • Return errors the model can read. A clear message lets it retry with better arguments.
  • Authenticate everything remote. An unauthenticated tool endpoint is an open door. See MCP security for WordPress.

The WordPress route

WordPress 6.9 bundles the Abilities API, a core registry where code declares what it can do, with a name, a description, an input and output schema and a permission callback. The official WordPress MCP adapter turns registered abilities into MCP tools and mounts a server over HTTP. So on WordPress you do not write protocol code at all: you register an ability. The background is in the WordPress Abilities API guide.

Here is an ability that counts drafts, placed in a plugin or an mu-plugin:

add_action( 'wp_abilities_api_categories_init', function () {
    wp_register_ability_category( 'my-plugin', array(
        'label'       => 'My Plugin',
        'description' => 'Abilities provided by My Plugin.',
    ) );
} );

add_action( 'wp_abilities_api_init', function () {
    wp_register_ability( 'my-plugin/count-drafts', array(
        'label'               => 'Count drafts',
        'description'         => 'Returns the number of draft posts.',
        'category'            => 'my-plugin',
        'output_schema'       => array( 'type' => 'integer' ),
        'execute_callback'    => function () {
            return (int) wp_count_posts()->draft;
        },
        'permission_callback' => function () {
            return current_user_can( 'edit_posts' );
        },
        'meta'                => array(
            'show_in_rest' => true,
            'mcp'          => array( 'public' => true ),
        ),
    ) );
} );

The permission_callback is the important part. It runs on every call, so the same capability rules that protect wp-admin protect the tool. Authentication is WordPress’s own: an application password over HTTPS works with any client that can send a header. See WordPress application passwords.

The mcp.public flag in meta matters. The adapter’s default server only exposes abilities that opt in this way, and it treats missing or malformed metadata as not public, so an ability without the flag stays invisible to MCP clients. See the MCP adapter repository for how it selects abilities in the version you run.

Using WP MCP instead of building your own

If the goal is to let an AI client work on a WordPress site, you may not need to build anything. WP MCP is a plugin that already runs a server at /wp-json/mcp/wpmcp-server with up to 407 tools (274 free, 133 Pro; the number on a site depends on active integrations), and takes a snapshot before every supported write. See the WordPress MCP server page, and pricing for the Pro tier.

It also works alongside your own abilities. Its ability bridge is off by default. A site owner switches it on with define('WPMCP_ENABLE_ABILITY_BRIDGE', true); in wp-config.php, or with the wpmcp_enable_ability_bridge filter. Then the execute-site-ability tool can run abilities that other plugins registered, including the my-plugin/count-drafts example above. Runs through the bridge are one-way actions: they are not snapshotted, so give such abilities narrow permission callbacks. Until the bridge is on, the tool refuses with opt_in_required.

Test it end to end

  1. Run the initialize and tools/list calls with curl and read the replies.
  2. Call each tool with valid arguments, then with invalid ones, and read the errors.
  3. Connect a real client and ask it a plain-language question that should trigger the tool.
  4. Check permissions: call it as a user without the capability and confirm it is refused.
  5. Put it behind HTTPS before anyone else connects.

Next steps

Related: the WordPress MCP adapter guide in more depth, and the beginner MCP tutorial.

Common questions

How do I build an MCP server?

Pick an SDK or write the protocol yourself. A server answers JSON-RPC 2.0 messages: initialize to start, tools/list to describe its tools, and tools/call to run one. Define each tool with a name, a description and an input schema, then serve it over stdio or HTTP.

Do I need an SDK to build an MCP server?

No. The protocol is JSON-RPC 2.0 over stdio or streamable HTTP, so any language that can read and write JSON can implement it. Official SDKs save time by handling the handshake, schema validation and transports.

How do I build an MCP server in WordPress?

Register your function as an ability with wp_register_ability, which is part of the Abilities API in WordPress 6.9. The official WordPress MCP adapter can then expose abilities as MCP tools, so you write the callback and the schema and the adapter handles the protocol.

How do I test an MCP server?

Send the JSON-RPC messages yourself with curl, or connect a client such as Claude Code and run its server status command. Check that tools/list returns your tools with correct schemas and that tools/call returns the result you expect.

Can WP MCP run abilities that other plugins register?

Yes, through the ability bridge, which is off by default. Once a site owner switches it on, the execute-site-ability tool can run abilities registered by other plugins. Those runs are one-way actions and are not snapshotted.

All WP MCP guides, or see every plugin integration. Topic: Connect an AI client.