<!-- pi-doc-last-commit: b0e6ddba3d04c809e8f6706fe73c7d3e049f69fa -->

# MCP Tools

## Overview

The **MCP Tools** screen lists the MCP abilities (tools) that are available on your site. You can enable or disable each tool from one page.

The plugin also adds two content tools:

- **Create Post or Page** — creates a new WordPress post or page.
- **Update Content Status** — changes the status of an existing post or page.

These tools are made available to MCP-enabled environments, such as AI agents and automation systems that are connected to your site.

## Requirements

- The **MCP Adapter** module must be installed and active.
- The WordPress Abilities API must be available on the site. If it is not available, the tools are not registered and the settings screen shows a warning.

If the MCP Adapter module is missing, the **MCP Tools** screen shows this notice:

> The MCP Adapter module is missing. Activate or install it to ensure all functionality is available.

The notice includes an **Install** or **Activate** button.

## How to Use

### Step 1: Open the Settings

1. Log in to the WordPress admin.
2. In the left menu, click **MCP Tools**.

Only users with the `manage_options` capability can open this screen. This is normally the administrator role.

![MCP Tools settings screen](images/mcp-tools-settings.png)

### Step 2: Review the Tool List

The page shows a table with these columns:

| Column | Description |
|---|---|
| **Enabled** | Checkbox that controls whether the tool is available. |
| **Tool** | The tool label. The ability category is shown below the label when one is set. |
| **Ability name** | The full ability name, for example `piweb-mcp-tools/create-post-or-page`. |
| **Description** | The tool description. |

Tools are grouped by ability namespace. Tools added by this plugin are grouped under `piweb-mcp-tools` and marked with the **This plugin** badge.

### Step 3: Enable or Disable Tools

- Leave a checkbox checked to keep the tool enabled.
- Uncheck a checkbox to disable that tool.

All tools are enabled by default.

### Step 4: Save the Settings

Click **Save Changes**.

WordPress saves the selection and shows its standard settings-saved notice.

When a tool is disabled:

- It is removed from the MCP server.
- It is removed from the REST API.
- It stays in the list on the **MCP Tools** screen so you can enable it again later.

## Configuration Options

### Enabled

Each row has an **Enabled** checkbox.

| Property | Value |
|---|---|
| Type | Checkbox |
| Default | Checked (enabled) |
| Applies to | Every ability listed on the screen |

The checkbox does not take effect until you click **Save Changes**.

If a disabled ability is no longer registered by its plugin, it remains listed with the description:

> This ability is disabled and is not currently registered.

This lets you turn the ability back on after the providing plugin is active again.

### Tool, Ability name, Description

These columns are read-only. They show the tool label, the full ability name, and the tool description.

The list can include abilities from other plugins, not only the tools added by this plugin. Disabling an ability from another plugin removes it from the MCP server and the REST API in the same way.

## Included Tools

### Create Post or Page

Creates a new WordPress post or page.

#### Input Fields

| Field | Type | Required | Allowed values | Default |
|---|---|---|---|---|
| `post_type` | String | No | `post`, `page` | `post` |
| `title` | String | Yes | Any text | — |
| `content` | String | No | HTML or block markup | Empty |
| `excerpt` | String | No | Any text | Empty |
| `status` | String | No | `draft`, `pending`, `publish` | `draft` |
| `slug` | String | No | URL slug | WordPress creates the slug from the title |
| `parent_id` | Integer | No | ID of an existing page. Used for pages only. | None |

#### Result Fields

| Field | Description |
|---|---|
| `success` | `true` when the content was created. |
| `message` | Result message. |
| `post_id` | ID of the new post or page. |
| `post_type` | `post` or `page`. |
| `status` | Status of the new content. |
| `edit_url` | Admin edit URL. |
| `permalink` | Public URL. |

#### Permissions

- The user must be able to edit posts.
- The user must be allowed to create the selected content type.
- Publishing requires permission to publish that content type. If the user cannot publish, the tool returns:

  > You are not allowed to publish. Use status draft or pending.

#### Validation

- `title` cannot be empty.
- `post_type` must be `post` or `page`.
- `status` must be `draft`, `pending`, or `publish`.
- `parent_id` must be the ID of an existing page. Otherwise the tool returns:

  > parent_id is not a valid page.

### Update Content Status

Changes the status of an existing post or page.

#### Input Fields

| Field | Type | Required | Allowed values |
|---|---|---|---|
| `post_id` | Integer | Yes | ID of an existing post or page |
| `status` | String | Yes | `draft`, `pending`, `publish`, `private`, `trash` |

#### Result Fields

| Field | Description |
|---|---|
| `success` | `true` when the status was changed. |
| `message` | Result message. |
| `post_id` | ID of the content. |
| `post_type` | `post` or `page`. |
| `old_status` | Status before the change. |
| `new_status` | Status after the change. |

#### Supported Content

By default, this tool only works with posts and pages. It does not change WooCommerce products, orders, coupons, or other custom post types.

#### Permissions

- The user must be able to edit posts.
- The user must be allowed to edit the specific post or page.
- Setting `publish` requires permission to publish that content type.
- Setting `private` requires permission to read private posts.
- Setting `trash` requires permission to delete the specific post or page.

If the content does not exist, is not a supported type, or the user cannot edit it, the tool returns the same message:

> Content not found, or you are not allowed to change it.

#### Status Behavior

- If the content already has the requested status, the tool returns success with the message:

  > Content already has this status.

- Setting the status to `trash` moves the content to the trash and keeps the previous status so the content can be restored.
- If the content is currently in the trash, the tool restores it first, then applies the requested status.
- `future` is not an accepted status. If a post has a future date and you set its status to `publish`, WordPress schedules it instead. The tool returns success with the message:

  > Content has a future date, so it was scheduled instead of published.

  In this case, `new_status` is `future`.

## Examples

### Example 1: Create a Draft Page

#### Configuration

| Field | Value |
|---|---|
| `post_type` | `page` |
| `title` | About Us |
| `content` | `<p>Learn more about our store.</p>` |
| `status` | `draft` |

#### Result

A new page titled **About Us** is created as a draft. The result includes the new `post_id`, the `edit_url`, and the page `permalink`.

### Example 2: Publish Is Blocked Without Permission

#### Configuration

| Field | Value |
|---|---|
| `post_type` | `post` |
| `title` | Summer Sale |
| `status` | `publish` |

The user can create posts but cannot publish them.

#### Result

The post is not created. The tool returns:

> You are not allowed to publish. Use status draft or pending.

The user can retry with `status` set to `draft` or `pending`.

### Example 3: Move a Post to the Trash and Restore It

#### Configuration 1

| Field | Value |
|---|---|
| `post_id` | 123 |
| `status` | `trash` |

#### Result 1

The post is moved to the trash. `old_status` shows the previous status and `new_status` is `trash`.

#### Configuration 2

| Field | Value |
|---|---|
| `post_id` | 123 |
| `status` | `draft` |

#### Result 2

The post is restored from the trash and set to draft. `old_status` is `trash` and `new_status` is `draft`.

### Example 4: Publish a Future-Dated Post

#### Configuration

| Field | Value |
|---|---|
| `post_id` | 456 |
| `status` | `publish` |

The post has a future publish date.

#### Result

The post is scheduled instead of published. The tool returns:

> Content has a future date, so it was scheduled instead of published.

`new_status` is `future`.

## Important Notes

- The **MCP Tools** screen lists abilities from all plugins that register through the WordPress Abilities API.
- Disabling a tool does not delete any content. It only removes the tool from the MCP server and the REST API.
- **Create Post or Page** only creates posts and pages. It does not create WooCommerce products, orders, or coupons.
- **Update Content Status** only changes posts and pages by default.
- Both tools run with the permissions of the user who is connected through MCP. A user cannot perform an action that their WordPress role does not allow.
- `future` cannot be passed as an input status. Scheduling happens only when a future-dated post is set to `publish`.

## Troubleshooting

### The MCP Adapter Notice Appears

The **MCP Adapter** module is not active.

1. Click **Install** or **Activate** in the notice.
2. Wait for the page to reload.
3. If the automatic install fails, install and activate **MCP Adapter** from the **Plugins** screen.

### No MCP Abilities Were Found

The screen shows:

> No MCP abilities were found. Please make sure the WordPress Abilities API is available.

Check that the WordPress Abilities API is available on the site and that the **MCP Adapter** module is active.

### A Tool Is Not Available to the AI Client

1. Open **MCP Tools**.
2. Confirm the **Enabled** checkbox is checked for the tool.
3. Click **Save Changes**.
4. Confirm the **MCP Adapter** module is active.

### A Status Change Is Rejected

The tool returns:

> You are not allowed to set this status.

The connected user does not have the permission required for that status. For example, publishing needs publish permission, private needs permission to read private posts, and trash needs delete permission for that item.

## Frequently Asked Questions

### Does unchecking a tool delete it?

No. The tool is only removed from the MCP server and the REST API. It stays in the list and can be enabled again.

### Can I create WooCommerce products with these tools?

No. **Create Post or Page** only supports posts and pages. **Update Content Status** only changes posts and pages by default.

### Can I schedule a post with Update Content Status?

Not directly. `future` is not an accepted status. Setting a future-dated post to `publish` makes WordPress schedule it.

### Why does a disabled tool still appear in the list?

Disabled tools stay visible so you can turn them back on. If the providing plugin no longer registers the tool, the row shows the message **This ability is disabled and is not currently registered.**

### Can I disable tools added by other plugins?

Yes. The **MCP Tools** screen lists abilities from every plugin and lets you enable or disable them.
