Getting StartedDesktop AI (MCP Server)

Desktop AI (MCP Server)

Set up Respira Desktop AI with the standalone MCP server, and understand how it coexists with the official WordPress MCP Adapter.

The official WordPress MCP Adapter is optional. From Respira 9.1.24 it is installed separately from WordPress.org. Respira works with that plugin when it is installed; the workflow on this page works without it.

Desktop AI setup

Desktop AI mode uses the Respira MCP server so tools like Cursor and Claude Code can safely edit WordPress with duplicate-before-edit workflows.

This page covers the standalone Respira MCP server. It can coexist with the official WordPress MCP Adapter and with Respira's browser surfaces.

Requirements

  • Node.js 20 or newer
  • Respira for WordPress plugin installed on your site
  • Connected site in your Respira account (dashboard MCP setup recommended)

Use respira.press → Dashboard → MCP Setup to generate client config, install command, or AI setup prompt for Cursor/Codex/Claude Code.

Step 1: Run the setup wizard

npx @respira/wordpress-mcp-server --setup

The wizard validates your site and writes the local configuration.

Step 2: Connect your AI tool

Use the configuration guide for your client:

Step 3: Test

npx @respira/wordpress-mcp-server --test

If the test succeeds, ask your AI:

  • "List all pages"
  • "Create a duplicate of the homepage"
  • "Analyze page speed for /"

What Desktop AI is best for

  • Batch edits and multi-step workflows
  • Repeatable, scriptable operations
  • Developer-heavy tasks in terminal/editor environments

Desktop MCP vs the official WordPress adapter

Respira supports both approaches:

  • Standalone Respira MCP server: local npx process, full established desktop workflow
  • Official WordPress MCP Adapter default/public server: WordPress-native discovery of the safe read-only Respira subset
  • Dedicated Respira MCP Adapter server: WordPress-native server for the broader Respira registry

Use the standalone MCP server when you want the usual Cursor/Claude Code workflow. Use the WordPress-native adapter path when you want WordPress to expose abilities directly.

Related: WordPress AI Stack Compatibility

Browser + Desktop together

Respira supports both modes at once:

  • Browser AI for quick edits
  • Desktop AI for advanced operations

Both modes use the same safety workflow, but tool totals differ by runtime and add-ons:

  • Desktop MCP: 82 WordPress tools + 21 WooCommerce tools (103 total with add-on active)
  • Browser AI/WebMCP: separate registry contract aligned to current plugin release

What plugin 9.1.0 and MCP server 8.4.0 change on the connection

Governance applies on every door

A tool switched off in Respira > Tools, and the Observe and Content profiles, bind on every way into the site: the REST routes the npm server calls, and the site's own MCP endpoint that Claude Desktop, claude.ai, ChatGPT and Respira AER use. Before 9.1.0 the endpoint's ability ids, which carry two prefixes, were only half stripped before the lookup, so a blocked tool went through on that door. Both id shapes now land on the same name.

The key travels twice

Every request the MCP server sends carries the credential in X-Respira-Authorization: Bearer <key> next to X-Respira-API-Key, and so do --setup and --doctor. Plugin 9.1.0 and later use that copy when a request arrives with no credential at all, which is what a host that strips the Authorization header, or a firewall that drops X-*-API-Key headers by name, leaves behind. It never overwrites a real Authorization header, so a staging password configured as httpAuth keeps working. It accepts only Bearer followed by a Respira key or access token, so it cannot log anyone in through application passwords or another plugin's scheme. Turn it off on the site with define( 'RESPIRA_DISABLE_AUTH_FALLBACK', true ); in wp-config.php. See Troubleshooting.

Errors say what to do

Errors on the connection, sign-in and approval paths carry two fields in their data, and the error envelope the agent sees shows both:

  • cause, one of credential, capability, licence, security_gate, approval, host_environment, invalid_input, not_found, conflict, rate_limited or server_error
  • retry_ok, whether sending the same call again can work

A revoked key says credential and no retry. A rate limit, or a site token that could not be checked because respira.press was out of reach, says retry. On the site's own MCP endpoint a failed tool call adds one sentence to the message and the pair in _meta["respira/error"].

Plan mode

respira_begin_session with mode: "plan" makes every write answer a proposed step instead of changing the site, and respira_apply_plan runs the steps once the person has said yes. It works in every client because it lives in tool results. See Plan mode for MCP clients.

Was this page helpful?