Using SEOPress abilities (Free & PRO)

What are SEOPress abilities?

SEOPress 10 registers a set of abilities on the new WordPress Abilities API. An ability is a clearly defined action (for example “read a post’s SEO title” or “create a redirect”) that AI assistants and automation tools can discover and run safely, with your existing WordPress permissions always enforced.

In practice, this lets you connect an AI agent (such as Claude, or any MCP-compatible tool) to your site and let it handle SEO tasks for you, instead of clicking through screens by hand.

Since SEOPress 10.4, abilities also cover taxonomy terms: categories, tags, WooCommerce product categories and custom taxonomies. An agent can read and update their SEO title, meta description, robots and social settings, find the terms with missing metadata and, with SEOPress PRO, get AI suggestions for them.

Requirements

• SEOPress (Free) 10.0 or newer for the core abilities, 10.4 or newer for the taxonomy term abilities.
• SEOPress PRO 10.0 or newer for the PRO abilities (redirects, structured data, AI generation), 10.4 or newer for the AI generation on terms.
• SEOPress Insights 3.1 or newer for the Insights abilities (rankings, competitors, backlinks).
• WordPress 6.9 or newer (the Abilities API is part of WordPress core from this version).
• An authentication method for external calls (we recommend Application Passwords).
• For the AI generation abilities: a configured AI provider or SEOPress AI Credits.

Enable abilities over the REST API

Abilities are off by default. SEOPress Free and PRO share one switch; SEOPress Insights has its own. Turning one on does not turn the other on.

SEOPress Free and PRO

1. Go to SEO > Advanced settings.
2. Open the Advanced tab, then the Abilities API section.
3. Turn on Expose abilities to AI agents and external tools.
4. Save.

SEOPress Insights

Insights has no toggle in its settings yet. Enable its abilities with a filter, in your theme’s functions.php or a small plugin:

add_filter( 'seopress_insights_abilities_api_rest_enabled', '__return_true' );

If you only run Insights and not SEOPress Free or PRO, this filter is all you need.

Once enabled, the abilities become reachable under the /wp-abilities/v1/ REST namespace, for any user who is already allowed to perform the underlying action.

Make your site “agent ready” (PRO)

SEOPress PRO can expose discovery signals so AI tools find and understand your content on their own. Enable Agent Readiness (under the Technical features) to publish an MCP server card (/.well-known/mcp.json), an llms.txt file and other /.well-known/ endpoints.

Connect an AI agent (MCP)

1. Enable Expose abilities to AI agents and external tools (and, on PRO, Agent Readiness).
2. Create an Application Password for the WordPress user the agent will act as (Users > Profile > Application Passwords).
3. In your MCP-compatible client, point it at your site and authenticate with that username and application password.
4. The client discovers the available abilities automatically and runs them on your behalf.

The agent can only ever do what that user is allowed to do. To limit its scope, connect it as a user with a restricted role.

Available abilities

Free (SEOPress): category seopress

The three list-posts-* abilities only return the posts the connected user may read, 20 per page by default (per_page up to 100, page to move through the results).

Free (SEOPress), taxonomy terms: since SEOPress 10.4, same seopress category

The term abilities take a term_id and read or write the same fields as the SEO metabox of the term edit screen. They work on any public taxonomy, unless Disable SEO metabox is turned on for it in SEO > Titles & Metas > Taxonomies. The listing only returns terms of the taxonomies the connected user may manage, 20 per page by default (per_page up to 100).

SEOPress PRO: same seopress category

SEOPress Insights: same seopress category

The Insights capabilities are the same ones that control access to the Insights screens. See SEOPress & Insights user capabilities to grant them to a role.

For developers

Three REST routes are available:

• GET /wp-json/wp-abilities/v1/abilities: list every ability
• GET /wp-json/wp-abilities/v1/abilities/<name>: one ability’s definition
• …/abilities/<name>/run: execute an ability

WordPress enforces the HTTP method from the ability’s annotations:

• read-only abilities → GET
• destructive and idempotent abilities (updates, deletes) → DELETE
• everything else (creation) → POST

The input of an ability always goes under an input key. With GET and DELETE, pass it as query parameters (?input[post_id]=123); with POST, send it as a JSON body ({"input": {…}}). The list endpoint returns the exact run URL for each ability, so MCP clients pick the right method automatically.

# List all abilities
curl https://example.com/wp-json/wp-abilities/v1/abilities \
--user "USERNAME:APPLICATION_PASSWORD"

# Read a post's SEO title and meta description (GET, read-only)
curl -g "https://example.com/wp-json/wp-abilities/v1/abilities/seopress/get-post-title-description/run?input[post_id]=123" \
--user "USERNAME:APPLICATION_PASSWORD"

# Find the product categories without a meta description (GET, read-only)
curl -g "https://example.com/wp-json/wp-abilities/v1/abilities/seopress/list-terms-missing-metadata/run?input[taxonomy][]=product_cat&input[missing]=description" \
--user "USERNAME:APPLICATION_PASSWORD"

# Set the SEO title of term 15 (DELETE, destructive + idempotent)
curl -g -X DELETE "https://example.com/wp-json/wp-abilities/v1/abilities/seopress/update-term-title-description/run?input[term_id]=15&input[title]=Garden+tools" \
--user "USERNAME:APPLICATION_PASSWORD"

# Create a redirect (POST)
curl -X POST https://example.com/wp-json/wp-abilities/v1/abilities/seopress/create-redirection/run \
--user "USERNAME:APPLICATION_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"input":{"origin":"/old-url/","destination":"/new-url/","type":"301"}}'

# Delete a redirect (DELETE, destructive + idempotent)
curl -g -X DELETE "https://example.com/wp-json/wp-abilities/v1/abilities/seopress/delete-redirection/run?input[id]=42" \
--user "USERNAME:APPLICATION_PASSWORD"

Permissions and security

• Abilities are off by default; you opt in with a single toggle.
• Every call runs as the authenticated user and re-checks that user’s WordPress capabilities. An agent can never exceed them.
• Per-post abilities require edit_post on the target post; per-term abilities require edit_term on the target term; global settings require manage_options.
• Since SEOPress 10.4, the abilities that change a post’s or a term’s SEO settings (update-post-*, update-term-*) refuse a role checked in SEO > Advanced settings > Security > SEO metaboxes: blocked roles, as the SEO metabox and the REST API already did. Reading stays allowed.
• Since SEOPress PRO 10.4, the AI abilities also check the AI generation roles of the same Security tab.
• Use Application Passwords and connect agents as a least-privileged user.

FAQ

Do I need SEOPress PRO? No. The free plugin already exposes 21 abilities, for posts, taxonomy terms and the global settings. PRO adds redirects, structured data, the technical audit and AI generation.

Will an agent change things without asking? Over REST, an authorized agent runs what it is asked to run. Inside the editor, the AI Assistant proposes changes for your review before applying them.

An ability returns “not found”. Make sure Expose abilities to AI agents and external tools is enabled and that the connected user can perform the action.

A term ability says the taxonomy is not supported. The taxonomy is not public, or Disable SEO metabox is turned on for it in SEO > Titles & Metas > Taxonomies. Term abilities only work where the SEO metabox of the term edit screen is available.