Get the plugin
WP MCP/Guides/Guide

By · Published

MCP tutorial: connect a client, call a tool and undo it

This MCP tutorial takes you from zero to a working setup in about half an hour. You will learn the few concepts that matter, connect an AI client to a real server, run your first tool calls, look at the messages underneath, and undo a change. The server used here is a WordPress site running WP MCP, but the concepts apply to any MCP server.

If you only want the Model Context Protocol tutorial in one sentence: a client asks a server what tools it has, the model picks one, the server runs it and returns JSON. Everything below is that loop, with real commands.

1. The concepts you need

Four ideas cover almost everything.

  • Client. The AI app you use: Claude Code, Claude Desktop, Cursor. It holds the conversation and decides when to call a tool.
  • Server. The program that offers capabilities. Here it is your WordPress site. See what an MCP server is.
  • Tool. A named action with a description and an input schema, such as list-posts. The model reads the description and sends arguments that match the schema. More in MCP tools explained.
  • Transport. How the messages travel. Local servers use stdio, where the client starts the server as a process. Remote servers use streamable HTTP, where each message is an HTTP POST to a URL. A website uses HTTP.

Servers can also offer resources (data a client can attach) and prompts (reusable instructions). They are covered in MCP resources and prompts, and you can ignore them for now. The wire format is JSON-RPC 2.0, described in the MCP protocol explained.

2. What you need before you start

Gather four things:

  • A WordPress site you can test on, ideally a staging copy, on WordPress 6.9 or later and PHP 8.1 or later.
  • The WP MCP plugin installed and active.
  • A dedicated WordPress user, such as an Editor, with an application password. Do not use your main administrator account. The application password guide shows the steps.
  • An MCP client. This tutorial uses Claude Code, and the notes below cover others.

The site’s MCP endpoint is:

https://your-site.com/wp-json/mcp/wpmcp-server

Replace your-site.com with your domain. The credential is a Basic header: the base64 of username:application-password. Make it in a terminal, keeping the spaces in the application password:

echo -n "mcp-editor:xxxx xxxx xxxx xxxx xxxx xxxx" | base64

3. Connect a client

For Claude Code, one command adds the server:

claude mcp add --transport http wpmcp \
  https://your-site.com/wp-json/mcp/wpmcp-server \
  --header "Authorization: Basic BASE64_VALUE"

Then start Claude Code and run /mcp. The server wpmcp should show as connected. The full options, including the project-level .mcp.json file, are in adding an MCP server to Claude Code.

Other clients differ in how they take the credential:

  • Claude Desktop does not read URL entries from its config file. Use the desktop bundle or a bridge. See Claude Desktop MCP servers.
  • Claude on the web uses a custom connector, which needs OAuth. WP MCP ships OAuth off, and the custom connectors guide explains how to switch it on.
  • Cursor takes the URL and header in its MCP settings, covered in Cursor MCP servers for WordPress.
  • ChatGPT needs OAuth and has not been fully tested with WP MCP, so skip it for this tutorial.

Not sure which client to pick? See MCP clients compared. For how sign-in works behind the scenes, see MCP authentication methods.

If the server does not connect, jump to the testing section below.

4. Your first tool calls

Start with reads, which change nothing. Type this into your client:

Tell me about this WordPress site: its name, the active theme and the post types it has.

The client asks for permission to use a tool, and then calls something like get-site-context and list-post-types. Approve the calls. Read the answer and compare it with what you know about the site. If they match, the connection works.

Next, ask for content:

List my five newest posts with their status and ID.

Behind that sentence, the client sends a tool call. The arguments are what the model derived from your words:

{
  "name": "wpmcp-list-posts",
  "arguments": { "per_page": 5 }
}

Two more read-only prompts worth trying:

Which tools does this server offer for working with media? Use the tool catalog.
Which of my posts mention "pricing" in the content?

The former points the model at list-tool-catalog, which reports what this particular site has. A full install registers up to 407 tools (274 free, 133 Pro), and a site sees fewer when optional plugins are inactive. If the full list is too large for your client, WP MCP has an optional compact mode that advertises five tools and reaches the rest through call-tool. That is a listing change only. It does not change what a call may do.

5. Make one small change

Now a write, on a test site. Ask for something harmless and easy to see:

Create a draft post titled "MCP tutorial test" with one paragraph that says hello. Do not publish it.

The model calls create-post, whose arguments include a title, content and a status that defaults to draft:

{
  "name": "wpmcp-create-post",
  "arguments": {
    "title": "MCP tutorial test",
    "content": "<p>Hello from MCP.</p>",
    "status": "draft"
  }
}

Open Posts in wp-admin and the draft is there. Then change it:

Change the title of that draft to "MCP tutorial test, edited" and add a second paragraph.

That uses update-post. Before it runs, WP MCP stores a snapshot of the post, so there is a state to return to.

6. Undo it

Every supported write is snapshotted before it happens, and each one gets an operation id. Ask the client to show them:

List the recent operations on this site.

It calls list-operations. To undo the edit:

Undo the last edit you made to the draft.

The model calls rollback-operation with the id:

{
  "name": "wpmcp-rollback-operation",
  "arguments": { "operation_id": "OPERATION_ID" }
}

To undo everything one session did, the tool is rollback-session, which skips undo points that were already undone and never applies one twice. You can do the same from wp-admin: the WP MCP screen lists every agent operation with a Restore button.

Undoing the creation of a post moves it to the trash, so you can restore it from there. A few kinds of change cannot be snapshotted, such as package updates and raw database row writes, and WP MCP responses say so instead of pretending. Those are off by default. The full picture is in undoing changes in WordPress.

Make this habit part of every session: read first, write small, check the result, and know how you would undo it before you ask for something big.

7. See the raw messages with MCP Inspector

When something fails, you cannot tell if the client, the model or the server is at fault. MCP Inspector removes the model. Run:

npx @modelcontextprotocol/inspector

Open the address it prints, choose Streamable HTTP, enter the endpoint URL, add an Authorization header with Basic BASE64_VALUE, and connect. You can list tools and run one by hand. The MCP Inspector guide covers every screen and the common errors.

The messages are plain JSON. A client starts with initialize, then asks tools/list, then sends tools/call:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

To see how a server produces those answers, read how to build an MCP server. It builds the handshake with curl and then shows the WordPress route.

8. Common problems

The server shows as failed or disconnected. Check the URL path first, then the credential. A 401 means the header is wrong. A 403 usually means the user’s role is too low, or a security plugin is blocking the request.

There are no tools, or very few. Run the status command in your client and confirm it connected. Then use the Inspector to see what tools/list returns. Some tools need an optional plugin to be active.

The model answers without calling a tool. Be explicit: “Use the WordPress tools to list my posts.” Check that the server is enabled in this chat.

A write is refused. Page-builder writes on WPBakery, Avada and Oxygen need an expected_hash from a prior read, which the model should fetch for you. Ask it to read the page first.

The client works on one machine and not another. Check that each uses its own copy of the credential, and that the site is reachable from that network.

9. Where to go next

You now have the whole loop: connect, list, call, check, undo. Every other MCP setup is a variation on it.

Common questions

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that lets an AI client discover and use tools, data and prompts from a server. The client asks the server what it offers, the model chooses a tool, and the server runs it and returns the result as JSON.

What do I need to follow an MCP tutorial?

You need an MCP client such as Claude Code, Claude Desktop or Cursor, and a server to connect to. For a hands-on run on WordPress you need a site with WP MCP installed, WordPress 6.9 or later, PHP 8.1 or later, and an application password.

What is the difference between an MCP client and a server?

The client is the AI app you talk to, such as Claude Code. The server is the program that offers tools, such as a WordPress site running WP MCP. The client connects to the server, lists its tools and calls them on the model's behalf.

Is it safe to let an AI change my WordPress site?

It is safer when you start with read tools, use a dedicated low-privilege user, and test writes on a copy. WP MCP snapshots every supported write before it happens, so you can undo one operation or a whole session, though a few change types cannot be snapshotted.

Why does my MCP client show no tools?

Usually the connection failed or the credential was rejected. Run the client's server status command, check for a 401 or 403 from the site, and use MCP Inspector to see the raw reply without a model in the way.

How do I undo a change made through MCP?

With WP MCP, call list-operations to see recent changes, then rollback-operation with an operation_id to undo one, or rollback-session to undo everything one agent session did. You can also press Restore on the WP MCP screen in wp-admin.

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