WPNerve

The native agent gateway for WordPress.

WPNerve is a self-hosted WordPress plugin that exposes carefully selected native WordPress Abilities as Model Context Protocol (MCP) tools. It runs entirely inside the WordPress installation: no relay, no SaaS control plane, no external database.

🇬🇧 Full docs in English below — 🇪🇸 Documentación completa en español más abajo.

Project status: early alpha. The 53-ability v1 surface, secure credential onboarding, persistent mutation idempotency, out-of-band high-risk confirmation, fail-closed endpoint rate limiting and privileged-surface hardening are implemented. Do not install this branch on a production site before the remaining beta gates and security review complete.

English

What is WPNerve?

WPNerve turns WordPress into a first-class citizen for AI agents. Instead of punching holes into wp-admin or using a SaaS relay that stores your credentials, you install one plugin and get a private, authenticated MCP endpoint on your own site. An agent can inspect and manage the selected surfaces using the same WordPress capabilities and permissions you already manage in the admin.

WPNerve deliberately does not expose “100% of WordPress.” Arbitrary SQL, PHP, shell, WP-CLI, filesystem and wp-config.php access remain outside the core; only reviewed, schema-defined abilities become MCP tools.

• Native. Built on the WordPress 6.9+ Abilities API instead of a parallel action registry.
• Self-hosted. Runs inside WordPress. No external service ever sees your requests or credentials.
• Secure by default. HTTPS required in production, WordPress-native authentication, fail-closed boundary controls and a central policy engine that denies destructive and privileged actions by default.

Why WPNerve

• WordPress 6.9+ native Abilities API, not a parallel action registry.
• MCP 2026-07-28 stateless HTTP plus compatibility with clients 2025-11-25 and 2025-06-18.
• WordPress Application Password and OAuth 2.1 authentication over HTTPS.
• A central policy gate separate from ability business logic.
• Least-privilege tool discovery: each user sees only the abilities they can execute subject to object-level authorization.
• Privacy-preserving audit events without credentials or tool arguments.
• Destructive and privileged risk classes denied by default.
• Persistent idempotency for every mutation.
• Short-lived WordPress-admin confirmation for destructive and privileged calls.
• Independent fail-closed rate limits for MCP and OAuth boundaries.
• Additional allowlists, redaction and object guards around users, plugins, options, transients and system diagnostics.

Architecture

flowchart LR
    A["MCP / OAuth client"] --> B["Rate limit"]
    B --> C["HTTP transport"]
    C --> D["Authentication"]
    D --> E["High-risk confirmation"]
    E --> F["Idempotency"]
    F --> G["Policy + object guards"]
    G --> H["Abilities API"]
    H --> I["WordPress"]
    G --> J["Audit log"]

The protocol, transport, policy, security, and WordPress ability layers are deliberately separate. A future protocol revision can replace the transport and dispatcher without rewriting content operations. See Architecture and Threat model.

Quick start

1. Install and activate the plugin on a WordPress 6.9+ site (PHP 8.1+).
2. Open Tools → WPNerve to see your MCP endpoint: https://your-site.com/wp-json/wp-nerve/v1/mcp
3. In Tools → WPNerve, select a dedicated WordPress user with only the capabilities the agent needs and click Generate WPNerve credential.
4. Copy the one-time secret or the ready-to-use client configuration. WPNerve verifies the credential against its MCP endpoint without persisting it.
5. Revoke WPNerve credentials from the same screen when a client is retired or a device is lost.
6. If you enable destructive or privileged risk classes and individual tools, approve each matching short-lived operation code in Tools → WPNerve before the client retries it.

Never commit or share the Application Password. If a client or device is lost, revoke the password immediately.

Selected tools

The implemented v1 catalog contains 53 abilities across content lifecycle, revisions, taxonomy, media, comments, menus, widgets, users, plugins, options and system diagnostics. See the full ability catalog.

Example requests

Replace the host, username, and Application Password. Never commit the password.

Discovery (modern protocol):

curl --user 'USERNAME:APPLICATION_PASSWORD' \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {
          "name": "manual-test",
          "version": "1.0.0"
        }
      }
    }
  }' \
  'https://example.com/wp-json/wp-nerve/v1/mcp'

List tools:

curl --user 'USERNAME:APPLICATION_PASSWORD' \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: tools/list' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {
          "name": "manual-test",
          "version": "1.0.0"
        }
      }
    }
  }' \
  'https://example.com/wp-json/wp-nerve/v1/mcp'

Call a tool:

curl --user 'USERNAME:APPLICATION_PASSWORD' \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: tools/call' \
  --header 'Mcp-Name: wp_nerve_site_status' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "wp_nerve_site_status",
      "arguments": {},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {
          "name": "manual-test",
          "version": "1.0.0"
        }
      }
    }
  }' \
  'https://example.com/wp-json/wp-nerve/v1/mcp'

Security posture

• The endpoint is private and requires an authenticated WordPress user.
• Production HTTP without TLS is rejected.
• Tool discovery and execution both pass through WPNerve policy and WordPress capability checks.
• MCP mirrored headers are checked against the JSON-RPC body.
• Unknown external WordPress abilities are not exposed automatically.
• Every mutation requires a credential-bound idempotency key.
• Destructive and privileged calls are hidden by default and require an expiring, argument-bound decision in the WordPress admin when enabled.
• Public MCP/OAuth boundaries have independent request budgets that fail closed.
• Arbitrary forwarding headers are not trusted to select the rate-limit subject.
• Protected options/transients and administrator-account boundaries have additional fail-closed guards beyond the broad risk class.
• Tool arguments, authorization headers, and Application Passwords are never written to the WPNerve audit table.

Report vulnerabilities privately according to SECURITY.md.

Requirements

• WordPress 6.9 or newer.
• PHP 8.1 or newer.
• HTTPS in production.
• Pretty permalinks and the WordPress REST API available.

Development

composer install
composer check        # lint + PHPCS + PHPStan level 8 + PHPUnit
composer test         # PHPUnit only

composer check runs PHP syntax validation, coding standards, PHPStan level 8, and the unit test suite. CI runs the same checks on PHP 8.1, 8.3, and 8.5, verifies version consistency, and publishes a coverage report on every push.

Documentation

• Architecture
• Threat model
• Beta-readiness roadmap
• Ability catalog v1
• Mutation idempotency
• High-risk confirmations
• Rate limiting
• Privileged surfaces
• Architecture decision records

License

GPL-2.0-or-later. See LICENSE.

Español

¿Qué es WPNerve?

WPNerve convierte a WordPress en un ciudadano de primera clase para los agentes de IA. En lugar de abrir agujeros en wp-admin o usar un relay SaaS que guarda tus credenciales, instalás un plugin y obtenés un endpoint MCP privado y autenticado en tu propio sitio. Un agente puede inspeccionar y gestionar las superficies seleccionadas usando las mismas capacidades y permisos de WordPress que ya administrás en el panel.

WPNerve no expone deliberadamente “el 100% de WordPress”. SQL, PHP, shell, WP-CLI, filesystem y wp-config.php arbitrarios quedan fuera del núcleo; sólo abilities revisadas y con schema se convierten en herramientas MCP.

• Nativo. Construido sobre la Abilities API nativa de WordPress 6.9+, no sobre un registro de acciones paralelo.
• Self-hosted. Corre dentro de WordPress. Ningún servicio externo ve tus pedidos o credenciales.
• Seguro por defecto. HTTPS obligatorio en producción, autenticación nativa de WordPress, límites fail-closed y un policy engine central que deniega acciones destructivas y privilegiadas por defecto.

Por qué WPNerve

• Abilities API nativa de WordPress 6.9+, no un registro paralelo de acciones.
• MCP 2026-07-28 stateless HTTP más compatibilidad con clientes 2025-11-25 y 2025-06-18.
• Autenticación con Application Password y OAuth 2.1 sobre HTTPS.
• Un gate central de políticas separado de la lógica de negocio de las abilities.
• Descubrimiento de herramientas con mínimo privilegio y autorización por objeto.
• Eventos de auditoría que preservan la privacidad: sin credenciales ni argumentos de herramientas.
• Clases de riesgo destructivas y privilegiadas denegadas por defecto.
• Idempotencia persistente para toda mutación.
• Confirmación breve en el panel de WordPress para llamadas destructivas y privilegiadas.
• Rate limiting independiente y fail-closed para MCP y OAuth.
• Allowlists, redacción y protecciones específicas para usuarios, plugins, options, transients y diagnósticos del sistema.

Arquitectura

flowchart LR
    A["Cliente MCP / OAuth"] --> B["Rate limit"]
    B --> C["Transporte HTTP"]
    C --> D["Autenticación"]
    D --> E["Confirmación de alto riesgo"]
    E --> F["Idempotencia"]
    F --> G["Policy + object guards"]
    G --> H["Abilities API"]
    H --> I["WordPress"]
    G --> J["Audit log"]

Las capas de protocolo, transporte, políticas, seguridad y abilities están separadas a propósito. Una revisión futura del protocolo puede reemplazar el transporte y el dispatcher sin reescribir las operaciones de contenido. Ver Arquitectura y Modelo de amenazas.

Inicio rápido

1. Instalá y activá el plugin en un sitio con WordPress 6.9+ (PHP 8.1+).
2. Abrí Herramientas → WPNerve para ver tu endpoint MCP: https://tu-sitio.com/wp-json/wp-nerve/v1/mcp
3. En Herramientas → WPNerve, seleccioná un usuario de WordPress dedicado con sólo las capacidades necesarias y pulsá Generate WPNerve credential.
4. Copiá el secreto de única visualización o la configuración lista para usar. WPNerve verifica la credencial sin persistirla.
5. Revocá las credenciales desde la misma pantalla cuando retires un cliente o pierdas un dispositivo.
6. Si habilitás clases y abilities destructivas o privilegiadas, aprobá cada código de operación en Herramientas → WPNerve antes de que el cliente reintente.

Nunca commitees ni compartas la Application Password. Si perdés un cliente o dispositivo, revocá la contraseña de inmediato.