WordPress 7.0 ships the Connectors API, and if you build plugins, this is the most significant new surface area in WordPress core since the REST API landed in 4.7. The Connectors API provides a standardized way for plugins to expose capabilities to external systems: AI agents, automation tools, external services, and anything else that needs to interact with your plugin programmatically. This is a deep dive into what it is, how it works, and what you need to do to prepare your plugin for it.
Note: WordPress 7.0 is still in RC as of this writing. API signatures and specific hook names may change slightly before final release. The architectural direction, however, is settled, this article focuses on that architecture, not the exact final method names.
What the Connectors API Actually Is
The Connectors API is a registry and invocation layer that lets plugins declare “connectors”, named, schema-described capabilities that external callers can discover and execute. Think of it as a formal contract between your plugin and the outside world. Instead of external systems having to know your REST API endpoints, action hooks, or shortcode syntax, they can query the WordPress Connectors registry to discover what your plugin can do and call those capabilities through a unified interface.
The primary motivation is AI agents. WordPress 7.0 is being developed alongside a broader push toward agentic WordPress integrations, AI assistants that can take actions on WordPress sites autonomously. For that to work safely and reliably, AI agents need a structured way to discover and invoke plugin capabilities without having to understand the implementation details of each plugin. The Connectors API provides that layer.
But the use cases extend well beyond AI. Automation tools like Zapier and Make.com, CI/CD pipelines that need to trigger WordPress operations, Headless WordPress setups that consume plugin functionality from external frontends, and MCP server integrations, all of these benefit from a standardized connector interface. The MCP server approach we covered for WordPress Playground is one concrete example of the direction this is heading.
Core Concepts: Connectors, Capabilities, and the Registry
The Registry
WordPress 7.0 introduces a global Connectors Registry, a singleton that aggregates all registered connectors across all active plugins. External callers query the registry to discover available connectors. The registry handles discovery, schema validation, permission checking, and invocation routing. Your plugin’s job is to register connectors with the registry; everything else is handled by core.
Connectors
A connector is a named capability with a defined input schema, output schema, and a callback function. It is similar to a REST API endpoint in spirit, but operates at a lower level, it does not require HTTP, does not go through the WP_REST_Server, and can be invoked in any execution context including WP-CLI, cron jobs, and programmatic PHP calls from other plugins. A connector definition includes:
- Name, a namespaced identifier like
my-plugin/create-item - Description, human-readable text that AI agents and documentation tools consume
- Input schema, a JSON Schema-compatible array defining expected parameters
- Output schema, a JSON Schema-compatible array defining what the connector returns
- Callback, the PHP callable that executes the capability
- Permissions callback, a callable that determines whether the current context is authorized to invoke this connector
Capabilities
A capability is a single unit of work your plugin exposes. Well-designed capabilities are atomic (they do one thing), idempotent where possible, and clearly scoped. Rather than exposing a single “do everything” connector for your plugin, you expose a collection of granular capabilities, create a post, get a post, update a setting, send a notification, each as its own named connector. This granularity is important for AI agent safety: an agent should only be able to invoke the specific capabilities it needs for a task, not arbitrary plugin functionality.
Registering a Connector: The Pattern
Connector registration follows a pattern similar to registering a REST route. You hook into wp_connectors_init (or the equivalent final hook name in 7.0 release) and call the registry’s register method. Here is the conceptual structure:
A few things worth noting in this pattern. The permissions_callback runs before the main callback, if it returns false or a WP_Error, the invocation is rejected. This is your authorization gate; treat it as seriously as you would a REST API permission check. The input_schema is used by the registry for automatic validation before your callback is invoked, which means your callback can trust that required parameters are present and of the expected type. The output_schema documents what callers should expect back, it does not enforce the return value but is used by tooling (AI agents, documentation generators) to understand your connector’s contract.
Permission Design: The Most Important Part
The permissions model for Connectors is where most plugin developers will need to think carefully. Because connectors can be invoked by AI agents and automated systems, not just logged-in users clicking buttons, the permission surface is different from a traditional REST endpoint.
Context-Aware Permissions
The Connectors API passes a context object to your permissions callback that includes information about who is invoking the connector and in what context: an AI agent acting on behalf of a user, an authenticated REST request, a direct PHP call from another plugin, a WP-CLI command. Well-designed permission callbacks check both the capability and the context. An AI agent that has been granted “editor” level access should not be able to invoke a connector that only administrators should use, even if the underlying WordPress user account has admin capabilities.
Principle of Least Privilege
Design each connector with the minimum permission it needs. A connector that reads a setting needs only read capability. A connector that creates content needs edit_posts. A connector that modifies plugin configuration needs manage_options. Do not grant connectors broader permissions than they require. When AI agents or automation tools request a list of available connectors, narrow scoped connectors are safer to grant access to.
Read vs Write Connectors
Make the read/write distinction explicit in your connector naming and permissions. A connector named my-plugin/get-settings is clearly read-only; one named my-plugin/update-settings is clearly write. This naming convention lets external systems (and the humans granting them access) make informed decisions about which connectors to authorize. Mixing read and write operations in a single connector makes permission management harder.
Schema Design: Writing for AI Agents and Automation Tools
The schema you provide for your connectors is not just documentation, it is the primary way AI agents understand what your connector does and how to use it. Write it as you would write documentation for a developer who has never seen your plugin.
Input Schema Best Practices
- Be explicit about types, specify
integer,string,boolean,arrayfor every parameter. Do not rely on implicit casting. - Include descriptions for every parameter, AI agents use these to determine which parameter maps to which piece of user intent. A parameter named
idwith no description is ambiguous; one with description “The post ID of the item to update” is not. - Mark required vs optional clearly, the
requiredarray in JSON Schema is used by the registry for automatic validation. Optional parameters should have sensible defaults defined. - Use enum for constrained values, if a parameter only accepts a fixed set of values (post status, sort order, format), enumerate them. This prevents invalid invocations and makes AI-generated calls more accurate.
Output Schema Best Practices
- Document success and error shapes separately if they differ significantly
- Include the keys that callers should use, if your connector returns a post object, document which keys are guaranteed to be present
- Note side effects in the connector description, “Creates a new post and triggers the
save_posthook” is information an AI agent needs to reason about whether to invoke this connector
A Practical Example: WooCommerce-Style Product Connector
To make this concrete, here is what a well-designed set of connectors might look like for a plugin that manages products. This follows the same granularity principle WooCommerce uses in its block-based APIs:
Notice the naming convention: plugin-slug/verb-noun. This is consistent with how REST API namespacing works and makes the registry discoverable. An AI agent querying the registry for all my-products/ connectors gets a complete picture of your plugin’s capabilities. The permission granularity is also explicit: read for reads, edit_products (a custom capability) for writes.
How the Connectors API Relates to the REST API
The Connectors API is not a replacement for the REST API. It is a complementary layer that operates at a different level. Here is how to think about when to use each:
| Use Case | REST API | Connectors API |
|---|---|---|
| External HTTP clients (mobile apps, headless frontends) | Yes | No |
| AI agents invoking plugin capabilities | Possible but awkward | Yes (designed for this) |
| Plugin-to-plugin programmatic calls | Possible via wp_remote_get | Yes (native PHP, no HTTP) |
| WP-CLI invocations of plugin logic | No | Yes |
| Capability discovery without prior knowledge of endpoints | Requires documentation | Yes (registry query) |
| Schema-validated inputs before callback runs | Manual (sanitize_* functions) | Automatic (registry validates) |
| Permission context for AI/agent invocations | Limited (auth headers only) | Rich (context object) |
The practical recommendation: build REST API endpoints for external HTTP clients and public-facing integrations. Build Connectors for capabilities you want to expose to AI agents, internal automation, and plugin-to-plugin orchestration. Many plugins will implement both, a REST endpoint for the HTTP interface and a Connector for the agentic interface that mirrors it.
Testing Connectors During Development
Testing Connectors requires a slightly different approach than testing REST endpoints. Since Connectors are not HTTP-based, you cannot use Postman or curl. The WordPress 7.0 developer tools include a Connectors debug panel in the Site Health screen that lists all registered connectors, their schemas, and lets you invoke them directly from wp-admin. This is the fastest way to iterate during development.
For automated testing, the WP test suite provides helpers for invoking connectors programmatically and asserting on return values. The pattern looks similar to testing REST endpoints: set up the context (user, permissions), invoke the connector, assert on the result. The Claude Code workflow we have been using for plugin development handles connector testing well, Claude can write connector registration code, invoke the connector in a test context, and iterate on the implementation in a single conversation.
One important difference from REST testing: the permissions context object needs to be mocked explicitly if you are testing agent-invoked connectors. The context for a human REST request differs from the context for an AI agent acting on behalf of a user, and your permission callbacks may behave differently for each.
What to Do Right Now: Preparation Checklist
WordPress 7.0 is in RC. Here is a concrete checklist for getting your plugin ready:
- Audit your plugin’s external interface, list every REST endpoint, WP-CLI command, and action hook that external systems already use. Each of these is a candidate for a corresponding Connector.
- Identify your top 5 capabilities, which things do users or integrations most commonly need to trigger in your plugin? These are your first-priority connectors.
- Draft schemas before writing code, write the input and output schemas first. This forces clarity about what each connector does and surfaces ambiguities early. Writing schema-first also makes the documentation automatic.
- Plan your permission model, decide which WordPress capabilities map to which connectors before implementation. Retrofitting permissions is harder than designing them upfront.
- Set up a WordPress 7.0 RC test environment, the WordPress Playground MCP server makes this trivial: spin up a Playground instance with WP 7.0 RC and test against it directly from your AI coding environment.
- Subscribe to the make.wordpress.org dev notes, the Connectors API spec will have final breaking changes before 7.0 release. The dev notes will document them.
The Bigger Picture: What This Means for the Plugin Ecosystem
The Connectors API changes what it means to build a WordPress plugin in a meaningful way. Until now, plugin developers built for human users, the interface was forms, metaboxes, shortcodes, and settings pages designed for people to click. The Connectors API adds a parallel interface layer designed for machines to consume.
This creates a new quality bar for the plugin ecosystem. Plugins that register well-designed connectors become first-class citizens in AI-powered WordPress workflows. Plugins that do not register connectors can still be invoked by AI agents through the REST API, but with less structure, less permission granularity, and less discoverability. Over the next two to three years, connector support will likely become a de facto requirement for plugins that want to be competitive in a market where AI-assisted site management is increasingly common.
The analogy to the REST API landing in WordPress 4.7 is apt. When REST launched, some plugin developers added REST endpoints immediately and built a significant integration advantage. Others waited and played catch-up as headless WordPress adoption grew. The Connectors API is a similar inflection point, the first-movers who ship well-designed connectors in time for WordPress 7.0 will be positioned to benefit from the AI-agent workflow wave that is already building. If you have been using AI tools in your WordPress development workflow, adding connector support to your plugins is a natural extension of that investment.
Error Handling and Idempotency: Designing for AI Agents
When a human makes a mistake in a form, they read the error message and correct it. When an AI agent receives an error, it needs structured information to decide what to do next, retry, fall back to a different approach, or surface the error to the user. This makes error handling in connectors more important than in traditional WordPress code paths.
Always return WP_Error for failures, not false or null. A WP_Error with a machine-readable error code, a human-readable message, and relevant data gives the calling agent enough context to reason about the failure. The error code should follow the pattern my-plugin/error-type, namespaced to avoid collisions. Include the HTTP status equivalent in the error data array ('status' => 404) so tooling can normalize it appropriately.
Idempotency matters more for connectors than for most other WordPress APIs because AI agents can retry failed operations. A connector that creates a resource should ideally support an idempotency key parameter, a client-provided unique identifier that lets the connector detect duplicate invocations and return the existing result rather than creating a second resource. For connectors that update or delete resources, natural idempotency is usually built in. For creation connectors, consider adding an optional idempotency_key parameter that you store in post meta and check before creating.
Write operations should also document their side effects explicitly in the connector description. “Creates a new order and sends the customer a confirmation email” is information an AI agent needs to decide whether to invoke the connector in a testing context. Side effects that cannot be undone (emails sent, payments charged, notifications pushed) should be called out clearly.
How Connectors Relate to the WordPress MCP Server
If you have been following the WordPress MCP server announcement (which we covered in depth in Connect AI Coding Agents to WordPress Playground with MCP), you might be wondering how MCP tools and the Connectors API relate. They operate at different layers and serve complementary roles.
The WordPress MCP server exposes WordPress operations to AI coding assistants like Claude Code and Cursor during development. It is a development tool, you use it to give your AI coding agent the ability to query posts, run WP-CLI commands, and inspect site state while you are building. Connectors are a runtime API, they are registered on production sites and invoked by external systems operating on live WordPress installations.
The practical relationship: the WordPress MCP server is an excellent tool for building and testing your Connectors implementation. During development, your AI coding agent can invoke your plugin’s connectors directly through the Playground MCP server, inspect the results, and iterate on the implementation. The same connector code that you test against WordPress Playground via MCP in development is the code that runs in production when an AI agent invokes your connector on a live site. This tight feedback loop between development tooling and the runtime API is one of the more underappreciated aspects of the WordPress 7.0 developer story.
Frequently Asked Questions
Do I need to update my plugin before WordPress 7.0 ships?
No. Connectors are opt-in. Your plugin will continue to work without any changes after the WordPress 7.0 update. The question is whether you want to be among the first plugins with connector support when AI-powered WordPress workflows start to adopt the API in earnest. Adding connectors proactively is a competitive advantage, not a requirement for compatibility. A good approach is to start small: pick your two or three most-called capabilities and register those as connectors first, then expand coverage incrementally over subsequent plugin releases.
Will the Connectors API break existing REST API integrations?
No. The Connectors API is additive. REST API endpoints continue to work exactly as before. The two systems are independent and serve different use cases. Adding connectors to your plugin does not change or interfere with your existing REST implementation.
How does the Connectors API handle connector versioning?
The connector name is the version surface. The recommended pattern is to include a version in the connector name when you introduce breaking changes: my-plugin/v1/create-item versus my-plugin/v2/create-item. Both connectors can coexist in the registry during a deprecation period. External callers can continue using the v1 connector while migrating to v2 at their own pace.
Can connectors be invoked across a WordPress multisite network?
Connectors are registered per-site by default. A connector registered on Site A in a multisite network is not automatically available on Site B. For network-wide connector registration, the WordPress 7.0 API includes a network scope flag in the registration call. Network-scoped connectors require super admin permissions by default, which can be narrowed via the permissions callback.
Is there a performance cost to registering many connectors?
Registration is lightweight, connectors are registered as an in-memory array during the init phase, not written to the database. A plugin registering twenty connectors adds negligible overhead to page load. The performance cost only materializes when connectors are invoked, and then only for the callback itself (which is your code, not the registry infrastructure).
AI in WordPress api-first architecture Connectors API Developer Tools WP 7.0
Last modified: March 22, 2026
