Support & Troubleshooting

Troubleshooting guides for Respira for WordPress, including MCP server connection issues, API key errors, page builder detection problems, and how to get direct support.

Getting Support

All Respira licenses include technical support:

Starter plan: Email support at word@respira.press
Agency plan: Priority email support at word@respira.press
WooCommerce add-on: Technical support included with €95/year subscription

Response time: Typically within 24 hours
Who responds: Mihai (founder), not a support bot
What to include: WordPress version, Respira version, error messages, what you were trying to do

Before contacting support, check this troubleshooting guide. Many common issues have quick solutions below.

Quick Diagnostics

Before diving into specific issues, run these commands to check your setup:

# Test your connection
npx @respira/wordpress-mcp-server --test

# List configured sites
npx @respira/wordpress-mcp-server --list

# Re-run setup wizard
npx @respira/wordpress-mcp-server --setup

Recommended version baseline

Respira for WordPress: 8.0.0+
MCP server: 8.0.0+
WooCommerce add-on: 4.0.0+ (v4.0.0 requires plugin 8.0.0 or newer)

Respira ships fixes almost every week, so the reliable baseline is simply the latest release of each. If you are on older versions, update first before deep debugging.

Gathering information for support

Before requesting support, gather the following:

Exact error messages shown in WordPress or in the MCP server console
Output from --test command
Your site URL, including protocol (https://)
Respira for WordPress plugin version
Whether the issue happens on a specific page, builder, or environment

Common issues

MCP server not connecting

Quick fix: Run the setup wizard again:

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

Other checks:

Check that Node.js 18+ is installed: node --version
Verify your config file exists at ~/.respira/config.json
Run npx @respira/wordpress-mcp-server --test to test your connection
Review the MCP server console output for runtime errors
Confirm your system firewall or host environment is not blocking local connections
Restart your AI assistant (Cursor, Claude Code, etc.) after configuration changes

Browser connector: sign-in opens a "Page not found" on `/authorize`

This is the most common browser-connection failure (Claude Desktop, claude.ai, ChatGPT, Cursor). If the sign-in tab opens something like https://your-site.com/authorize?...&client_id=respira_site_... and shows a 404 / "Page not found", the cause is almost always a Client ID filled into the connector.

A browser connector connects by URL only. When you also give it a Client ID, the assistant stops doing automatic discovery and builds the sign-in URL on your own WordPress address — which has no /authorize page by design, so it 404s.

The respira_site_... value people paste there is the site token from the dashboard's Connected Sites panel. It is not an OAuth Client ID — it is only for the command-line / npm setup (header auth) and must never go in a browser connector.

Fix:

Remove the connector.
Re-add it with only the MCP URL in the URL field: https://your-site.com/wp-json/respira/v1/mcp
Leave Client ID and Client Secret blank. Do not paste the respira_site_... token anywhere in the connector.
Approve the sign-in tab that opens on respira.press — sign-in always happens there, never on your own site.

Two things that are not the problem

There is no /authorize route on your WordPress site, and the plugin does not need one. The plugin is only the destination the AI edits; the OAuth sign-in lives on respira.press. Do not try to "register an authorize route" or reinstall to fix this.
"License: Not synced", "Plan unavailable", or "0 API keys" in the plugin panel does not block a browser connection. That panel is the plugin's local view; the browser flow issues its own token from respira.press and needs no plugin API key. "0 keys" is normal for a browser-only connection.

MCP update hints appear in tool responses (`respira_mcp_update`)

This is informational, not a runtime failure.

Upgrade with: npx -y @respira/wordpress-mcp-server@latest
Restart your AI client after upgrade
Disable daily update checks with: RESPIRA_MCP_DISABLE_UPDATE_CHECK=1

API key not working

Confirm the key starts with respira_ or respira_site_ and has no extra spaces
Check that the API key is active in WordPress Admin (Respira → API Keys)
Ensure your site URL is correct and includes https://
Review the audit log in WordPress Admin for failed API requests
Verify the key has not expired or been revoked
Try generating a new API key

Page builder not detected

Confirm the intended page builder plugin is installed and active
Make sure the page or post was created with that builder
Some page builders require specific Respira license tiers
If detection still fails, check for JavaScript errors in the browser console
Try reading the page directly: Read page ID 123

Elementor 500 errors (URL control / `ltrim()` / inject failures)

If Elementor writes fail intermittently or return 500-level errors:

Update the Respira plugin and MCP server to the latest release
Re-run setup: npx @respira/wordpress-mcp-server --setup
Re-test: npx @respira/wordpress-mcp-server --test
Retry the same operation once after upgrade

Recent fixes include safer handling for link-control array payloads, stricter payload normalization, and cache invalidation on fallback save paths.

Changes not saving

If direct editing is enabled, confirm whether you chose live or duplicate in preflight
For duplicate edits, verify you're reviewing the duplicate
Ensure your WordPress account has permission to edit the page or post
Review the audit log for validation or publishing errors
Confirm that content validation is passing
If drafts are not updating, clear any server-level or plugin caching

Setup page is read-only after upgrade

This is expected in the 4.0 admin IA refresh.

Edit plugin controls in Respira → Settings
Use Setup → Health & Permissions as a readiness/status summary

Windows: 'npx' not recognized

If you see 'npx' is not recognized as an internal or external command:

Use the full path: C:\Program Files odejs px.cmd
Or install globally: npm install -g @respira/wordpress-mcp-server
Ensure Node.js is in your system PATH

Site URL mismatch

The site URL in your config must match exactly what WordPress reports:

In WordPress Admin, go to Settings → General
Copy the "WordPress Address (URL)" exactly
Update dashboard-generated MCP config, or ~/.respira/config.json for manual mode
Re-run npx @respira/wordpress-mcp-server --test

Helpful resources

FAQ

How do I know if the MCP server is running?

Run npx @respira/wordpress-mcp-server --test to check the connection. If successful, you'll see a confirmation message with your site details.

What should I do if edits are not appearing on my site?

First check whether you are editing a duplicate page (this is expected behavior). Go to Respira → Approve Edits in WordPress Admin to approve changes. Also verify user permissions and clear any caching layers.

Can I use Respira on a staging or local site?

Yes. Ensure the API key and site URL in ~/.respira/config.json match the environment you are using. For local development, the MCP server runs on your machine alongside the AI assistant.

How do I switch between multiple WordPress sites?

Use wordpress_switch_site in your AI assistant, or configure multiple sites in ~/.respira/config.json and use --list to see them.

What information should I include when contacting support?

Include your site URL, plugin version, output from --test command, a description of the issue, and any logs or exact error messages.

How do I contact support?

Email: word@respira.press
Use the account dashboard for license-specific support options

Direct support

Respira for WordPress is a commercial plugin with dedicated support. For direct assistance, contact the team using the channels above and include as much diagnostic information as possible.

Was this page helpful?