Everything you need to
run GripMCP well.

Install the plugin, connect your assistant, choose what it may do, and fix the rare connection that won’t. Plus a reference for developers who want to extend it.

Popular: Connect Claude Approvals Won’t connect Access tokens

Quick start

Upload, switch the endpoint on, paste one address into Claude. About a minute.

Start here

Stay in control

Who can connect, which actions wait for you, and what gets logged.

Permissions

Fix a connection

Read the diagnostics log and match the reason to its fix.

Troubleshoot

Getting started

Overview & requirements

GripMCP turns your WordPress site into a Model Context Protocol (MCP) server. Your AI assistant connects to one address on your site and can then manage it in plain language, always as a real WordPress user, with that user’s permissions.

You need	Details
WordPress	6.2 or later (tested up to 7.1)
PHP	7.4 or later (tested up to 8.5)
HTTPS	Required by default. Tokens sent over plain HTTP can be intercepted.
An MCP client	Claude (web, desktop, mobile or Claude Code), or any client that supports the Streamable HTTP transport.
Pretty permalinks	Only for the short `/mcp` address. Without them the longer REST address works instead.

Install the plugin

Free

Upload the zipIn wp-admin go to Plugins › Add New › Upload Plugin and choose the GripMCP zip. You can also upload the gripmcp folder to /wp-content/plugins/.
Activate GripMCPA GripMCP item appears in the admin menu, with four tabs: Setup, Permissions, Access and Activity.
Switch the endpoint onIt is off until you do. See the next section.

On a paid plan? Creator, Operator and Fleet are a separate download from your purchase. Install it the same way; its licence decides which tools are available. Without an active licence it runs as the free Explorer plan. To move back to the free plugin, install and activate it first, then delete the paid copy: your settings, connected apps and activity log carry over.

Switch the endpoint on

Open GripMCP in the admin menu and flip the switch at the top right. It saves as soon as you change it. Then copy your endpoint address from the Setup tab. It looks like this:

Endpoint

https://your-site.com/mcp

The short /mcp address needs pretty permalinks (Settings › Permalinks set to anything but “Plain”). Without them, the Setup tab shows the longer REST address instead, which works with any permalink setting:

Fallback endpoint

https://your-site.com/?rest_route=/gripmcp/v1/rpc

Connecting

Connect Claude in one click

Claude on the web, desktop and phone connects without any token or config file. You sign in to WordPress and approve, and Claude can do only what your account can do.

Add a custom connectorIn Claude, open Settings › Connectors and choose Add custom connector.
Paste your endpoint addressThe one you copied from the Setup tab.
Sign in to WordPress and approveClaude opens your site’s sign-in page and a consent screen. Click Approve and you’re connected.

One-click connect needs three things. HTTPS; a site at the root of its domain (not in a subfolder); and a site Claude can reach from the internet, since it connects from Anthropic’s cloud, not your computer. If a security plugin blocks /.well-known/ addresses, allow them. A site in a subfolder can connect with an access token instead.

This is the standard MCP authorization flow (OAuth 2.1 with PKCE and dynamic client registration), so other MCP clients that support it connect the same way.

Connect with an access token

For apps you set up with a command or a config file, such as Claude Code. Create a token on the GripMCP › Access tab and copy it straight away: it is shown only once.

Tokens are stored hashed, and you can revoke one at any time.
They expire after 90 days by default. You can choose 30 days, 1 year or never.
They work only at the GripMCP endpoint, never on the rest of the WordPress API.
No plan limits how many tokens or connected apps you have.

Claude Code

claude mcp add --transport http wordpress https://your-site.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

mcpServers config file

{
  "mcpServers": {
    "wordpress": {
      "type": "http",
      "url": "https://your-site.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Prefer WordPress’s own credentials? A username with an Application Password works too, sent as HTTP Basic auth.

Who can connect

Administrators can always connect. Any other account can connect only when its role is ticked under Permissions › Who can connect. None are ticked by default, because on a shop or membership site anyone can create an account.

Whoever connects, every tool call is checked against that WordPress user’s real capabilities, exactly as wp-admin would check them. GripMCP never grants a capability the user doesn’t already have.

Tightest control: create a dedicated WordPress user with a limited role for each assistant, allow that role to connect, and connect as that user.

Permissions & safety

Destructive actions & approvals

Deleting content, users, plugins or themes, refunding an order, and changing who has admin-level access (making someone an administrator or shop manager, or changing such an account’s email or password) count as destructive. Choose how they behave on the Permissions tab:

Off

The assistant cannot run them.

Ask me first Default

Each one waits for your approval in WordPress, and you see the exact action before it runs.

Allow

They run straight away, without asking.

How an approval works

The assistant gets a link to a page in your own wp-admin that shows what it wants to do, with all of its details.
Before it is held, GripMCP checks what the action would break: shortcodes or blocks still on your pages, plugins that depend on it, your homepage or a menu page, an image used as your logo, the last administrator.
You click Approve or Decline, signed in as yourself. There is no way for an assistant to approve its own request.
Requests waiting for you are also listed on the Approvals tab of the GripMCP screen, with a count on its menu item, so a lost link never strands one.
What you approve is exactly what runs. Each approval works once and expires after 30 minutes.

Paid plans add a few more switches. Editing theme and plugin files, installing packages and REST writes are each off until you switch them on. File edits are syntax-checked and backed up first, a PHP change to the active theme or an active plugin is tested by loading the site and undone if it causes a fatal error, and page-builder edits save a restore point.

Temporary debug logging

Nothing changes until your assistant switches debug logging on to look into a problem. It then records PHP errors to a private file on your site for the time it asked for, 5 minutes to 24 hours, and switches itself off. Errors are never shown to visitors.

To stop assistants switching it on, turn off “Let the assistant switch on debug logging” under More settings on the Permissions tab. Reading existing logs still works.

Activity log

Every tool call is recorded on the Activity tab: the time, the tool, the user, the result, how long it took and the IP address. How long entries are kept depends on your plan:

Plan	Kept for	Extras
Explorer (free)	3 days	—
Creator	7 days	—
Operator	90 days	Filters and CSV export
Fleet	90 days	Filters and CSV export

If a licence lapses or moves to a lower plan, the older entries stay stored for 30 more days, so renewing in that time brings them back.

What GripMCP stores

Everything stays in your own WordPress database and files:

Its settings, hashed access tokens, and OAuth clients and tokens
The activity log and the connection diagnostics log
File backups and page-builder restore points
A short list of recent PHP fatal errors

Deleting the plugin from the Plugins screen removes all of it. Themes your assistant created are left in place, like any other theme. GripMCP has no analytics of its own; the outside services it can contact are listed in our privacy policy.

Using GripMCP

What to ask

Talk to your assistant the way you’d brief a colleague who has wp-admin open. A few starting points:

Content Free

“Draft a post about our autumn sale, add it to the News category and set the hero image as featured.”

Site health Free

“The contact page is throwing errors. Turn on debug logging for 30 minutes and tell me what you find.”

Plugins Creator

“Which plugins have updates waiting? Update everything except WooCommerce.”

Store Operator

“Show me last week’s sales and list products with fewer than five in stock.”

Page builders Operator

“On the Elementor homepage, change the hero button text to ‘Book a demo’.”

Migration Fleet

“We’re moving to the new domain. Run a search and replace for the old address.”

See every area on the Capabilities page.

Plans & new tools

Each plan includes everything in the plans before it.

Explorer

Content, media, users, menus, comments, custom fields, settings, revisions, approvals, debug log, site health and plugin abilities.

Creator

Search, install, update, roll back and remove plugins and themes.

Operator

WooCommerce, Elementor, WPBakery and Divi 4, WP-CLI, read-only SQL, raw REST requests, 90 days of activity log with filters and CSV export.

Fleet

Theme and plugin file editing, theme drafts, new block themes, database search and replace.

Reconnect to load new tools. Assistants keep the tool list they loaded when they connected. After you upgrade, or activate WooCommerce or a page builder, reconnect GripMCP in your AI app. GripMCP tells the assistant when this is needed.

WooCommerce, page-builder and Abilities tools appear only on sites that have those features. Compare plans on the Pricing page.

Progress cards & in-chat uploads

In apps that show in-chat panels, such as Claude, requests that take several steps show one live card with each step and its result, then the outcome. In the same apps you can drag images onto an upload panel right in the conversation.

Apps without in-chat panels simply don’t get these. Developers can switch them off with the gripmcp/progress_cards and gripmcp/in_chat_uploads filters.

Troubleshooting

Connection diagnostics

If your assistant won’t connect, or a connector stops working, open GripMCP › Activity › Connection diagnostics. It lists every token issued and every refused request with the reason. Read the newest refusal and match it below.

Reason	What to do
`no_authorization_header`	Your server strips the Authorization header. Apply the .htaccess fix.
`https_required`	The request didn’t arrive as HTTPS. Common behind a proxy or CDN that ends TLS before WordPress.
`user_not_allowed`	The account’s role can’t connect. Tick it under Who can connect.
`refresh_token_revoked`	The account’s password changed, which signs its apps out. Remove the connector in your app and add it again.
Any other reason	Remove the connector in your app and connect again.
No entries at all	The request never reached WordPress: check DNS, a firewall, or a security plugin blocking `/.well-known/`.

Settings that stop every app from connecting, such as a switched-off endpoint, are shown on the GripMCP screen next to their fix.

Fix a stripped Authorization header

Some Apache and LiteSpeed setups drop the Authorization header before PHP sees it, and then every app is refused. The Setup tab tests for this when you open it and warns you. To fix it, add this to the very top of your site’s .htaccess:

.htaccess

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]
</IfModule>

Change the /mcp address

If your site already has a page at /mcp, give GripMCP a different short address in wp-config.php. Any single word works. Set it to an empty string to turn the short address off and use the longer REST address.

wp-config.php

define( 'GRIPMCP_SHORT_PATH', 'ai' );

Then copy the new address from the Setup tab into your assistant.

Report a problem

Open GripMCP › Activity › Report a problem and describe what you were trying to do. GripMCP writes the report for you, adding your WordPress, PHP and plugin versions, your GripMCP settings and the relevant error lines. It leaves out passwords, tokens, email and IP addresses and your content.

Free plan: click Copy post and send it to us through the contact page.
Paid plans: click Copy email and send it to support@gripmcp.com, or download it as a file.

The plugin never sends the report itself: only you do, after reading it.

Developers

Add your own tool

A tool is a class that extends Abstract_Tool, registered through the gripmcp/tools filter from your own plugin or your theme’s functions.php. No core files change. It is validated, permission-checked, logged and listed to assistants automatically.

my-plugin.php

use GripMCP\Tools\Abstract_Tool;
use GripMCP\Tools\Request_Context;
use GripMCP\Tools\Tool_Result;

final class My_Clear_Transients_Tool extends Abstract_Tool {

    public function get_name(): string        { return 'myplugin_clear_transients'; }
    public function get_title(): string       { return 'Clear expired transients'; }
    public function get_description(): string { return 'Delete expired transients from the database.'; }
    public function get_group(): string       { return 'site'; }

    public function get_input_schema(): array {
        return array(
            'type'                 => 'object',
            'properties'           => (object) array(),
            'additionalProperties' => false,
        );
    }

    protected function required_capability(): string { return 'manage_options'; }

    protected function run( array $args, Request_Context $ctx ): Tool_Result {
        delete_expired_transients( true );
        return $this->ok( 'Expired transients deleted.' );
    }
}

add_filter( 'gripmcp/tools', function ( array $tools ) {
    $tools[] = new My_Clear_Transients_Tool();
    return $tools;
} );

Authoring notes

Prefix tool names with your own prefix. wp_ and wc_ belong to GripMCP’s built-in tools.
Return results with $this->ok(), $this->data() (adds MCP structuredContent) or $this->fail().
Override is_read_only(), is_destructive() and is_idempotent() to set MCP annotations. Destructive tools follow the site’s approval setting.

The paid download also includes the full developer guide, as README.md in the plugin folder.

Still stuck?

Send us a report from the Activity tab, or get in touch.

Read the FAQ Contact us

Ready to connect your site?

Pick the plan that fits, install the plugin and connect your AI in about a minute.

See pricing See capabilities

Everything you need to run GripMCP well.