 |
VOOZH | about |
|
VOOZH | about |
This page provides practical, working examples for creating and testing MCP tools, resources, and prompts using the WordPress MCP Adapter. Each example demonstrates the minimum required configuration to expose WordPress abilities through the Model Context Protocol.
For comprehensive details on ability creation, schema design, and advanced features, see Creating Abilities. For setting up your development environment, see Development Environment. For information about the architecture and request flow, see Architecture.
The MCP Adapter automatically creates a default server that exposes all abilities marked with meta.mcp.public = true. This server is immediately available once the plugin is active.
| Property | Value |
|---|---|
| Server ID | mcp-adapter-default-server |
| REST Endpoint | /wp-json/mcp/mcp-adapter-default-server |
| Supported Transports | HTTP, STDIO (via WP-CLI) |
| Ability Filter | All abilities with meta.mcp.public = true |
| Default Permission Callback | is_user_logged_in() |
The default server is registered automatically by includes/mcp-adapter.php40-57 during the mcp_adapter_init action. Custom servers can be created using the McpAdapter::create_server() method as documented in Server Configuration.
Sources: docs/getting-started/basic-examples.md245-250 includes/mcp-adapter.php40-57
Tools execute actions and return results. The following example creates a tool that inserts WordPress posts with validation and permission checks.
The ability is registered using wp_register_ability() during the wp_abilities_api_init action:
docs/getting-started/basic-examples.md12-106
Key configuration elements:
| Field | Purpose |
|---|---|
input_schema | Defines required fields (title, content) and optional fields (status, category) with validation constraints |
output_schema | Specifies the structure of the returned data (post_id, post_url, edit_url) |
execute_callback | Implements the post creation logic using wp_insert_post() |
permission_callback | Restricts access to users with publish_posts capability |
meta.mcp.public | Exposes the ability through the default MCP server |
meta.annotations | Provides behavior hints (readOnlyHint, destructiveHint) |
The input schema is automatically validated against the ability definition before execution. The output schema is used by MCP clients to understand the response structure. No transformation is needed for object schemas - they pass through unchanged as shown in includes/Domain/Utils/SchemaTransformer.php56-62
Sources: docs/getting-started/basic-examples.md5-117 includes/Domain/Utils/SchemaTransformer.php20-92
Resources provide read-only access to data. They require a uri in the ability metadata and should set type: 'resource' for proper discovery.
docs/getting-started/basic-examples.md124-157
Key configuration elements:
| Field | Purpose |
|---|---|
meta.uri | Required for resources. Unique identifier (e.g., wordpress://site/config) |
meta.mcp.type | Set to 'resource' for proper auto-discovery via resources/list |
execute_callback | Returns structured data without modifying state |
permission_callback | Restricts access to administrators (manage_options) |
meta.annotations.audience | Indicates intended consumers (user, assistant) |
meta.annotations.priority | Relative importance (0.0 to 1.0) for resource ranking |
Resources are identified by their URI during resources/read requests. The ResourcesHandler includes/Transport/Handlers/ResourcesHandler.php looks up resources by URI and executes the underlying ability.
Sources: docs/getting-started/basic-examples.md119-169 docs/guides/creating-abilities.md544-577
Prompts generate structured messages for language models. They use meta.arguments or input_schema to define parameters and must return a messages array.
docs/getting-started/basic-examples.md178-229
Key configuration elements:
| Field | Purpose |
|---|---|
meta.arguments | Defines prompt parameters (name, description, required) in MCP format |
meta.mcp.type | Set to 'prompt' for auto-discovery via prompts/list |
execute_callback | Returns messages array with role and content fields |
content.annotations | Message-level metadata for specific content blocks |
meta.annotations | Template-level metadata describing the prompt's characteristics |
Instead of meta.arguments, prompts can define parameters using input_schema, which is automatically converted to MCP argument format by includes/Domain/Conversions/RegisterAbilityAsMcpPrompt.php This approach provides JSON Schema validation:
See docs/guides/creating-abilities.md586-601 for the complete example using input_schema.
Sources: docs/getting-started/basic-examples.md172-241 docs/guides/creating-abilities.md580-655
The following diagram illustrates the complete testing workflow using WP-CLI's STDIO transport:
The --user=admin flag sets the current user context for permission checks. The --server=mcp-adapter-default-server flag specifies which MCP server to use. For custom servers, replace with your server ID.
Sources: docs/getting-started/basic-examples.md261-271 docs/troubleshooting/common-issues.md28-32
The following table summarizes the key differences between the three MCP component types:
| Aspect | Tools | Resources | Prompts |
|---|---|---|---|
| MCP Method | tools/call | resources/read | prompts/get |
| Discovery Method | tools/list | resources/list | prompts/list |
| Required Metadata | meta.mcp.public = true | meta.uri (required)meta.mcp.type = 'resource' | meta.arguments or input_schemameta.mcp.type = 'prompt' |
| Return Value | Arbitrary structured data | Arbitrary structured data | {messages: [...]} array |
| Annotations Type | ToolAnnotations( readOnlyHint, destructiveHint, idempotentHint) | Annotations( audience, priority, lastModified) | Annotations( audience, priority, lastModified) |
| Typical Use Case | Execute actions, modify data | Provide read-only data access | Generate prompts for LLMs |
| Schema Support | Object or flattened | N/A (no input schema) | Arguments converted from input_schema |
Sources: docs/getting-started/basic-examples.md244-259 docs/guides/creating-abilities.md312-363
The following diagram shows how abilities are registered, filtered, and exposed through the default MCP server:
Key Points:
wp_register_ability() during the wp_abilities_api_init actionmeta.mcp.public = true are exposed through the default servermeta.mcp.type field determines which converter is used (tool, resource, or prompt)meta.mcp.type is not specified, abilities default to type: 'tool'Sources: includes/mcp-adapter.php40-57 docs/guides/creating-abilities.md14-36
For simple abilities that accept or return single values, the MCP Adapter supports flattened schemas that are automatically transformed to MCP-compatible object format:
The SchemaTransformer class includes/Domain/Utils/SchemaTransformer.php20-92 handles this transformation automatically. Key behaviors:
string, number, integer, boolean, array) are wrapped includes/Domain/Utils/SchemaTransformer.php64-70"input" as the wrapper property"result" as the wrapper property (see docs/guides/creating-abilities.md174-194)For detailed information on flattened vs object schemas, see Creating Abilities and Schema Transformation.
Sources: includes/Domain/Utils/SchemaTransformer.php20-92 docs/guides/creating-abilities.md84-144 tests/Unit/Domain/Utils/SchemaTransformerTest.php20-313
After completing these basic examples, explore:
For troubleshooting common issues, see Troubleshooting Guide.
Refresh this wiki