Support & Troubleshooting

Getting Support

All Respira licenses include technical support:

• Every plan (Maker, Builder, Studio, Founder): email support at word@respira.press
• WooCommerce add-on: technical support included while the subscription is active

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.

We're here to help

Use this page to diagnose and resolve the most common Respira for WordPress issues, including MCP server errors, API key failures, page builder detection problems, and publishing or saving issues.

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 20 or newer 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:

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

Respira > Troubleshoot in wp-admin (plugin 9.1.0)

When an agent will not connect, the site can check itself. Respira > Troubleshoot runs the connection checks from the site's own server and shows each one as pass or fail, with the cause and one next step:

• the REST API, and the ?rest_route= address
• a web page where JSON belongs: a Cloudflare challenge, a firewall's block page, a maintenance plugin or the site's own front page, each named
• the Authorization header, and Respira's backup header (X-Respira-Authorization)
• the MCP address, and sign-in discovery at /.well-known/oauth-protected-resource
• a bot filter that refuses the user agents claude.ai's and ChatGPT's connectors send, asked twice before it is called a rule
• the security plugins and CDNs in front of the site
• whether the site can reach respira.press

Copy report for your host produces a plain-text report for a hosting support team: what failed, what to allow, and the id of every test request (each carries an X-Respira-Probe-Id header, so the host can find it in its logs). It contains no passwords, cookies, keys or page contents. Setup links to the screen when linking fails or an agent will not connect.

The host strips the Authorization header

Apache running PHP as CGI or FastCGI, some LiteSpeed setups and a few managed-host edges drop the Authorization header before PHP runs. Every client that authenticates with Authorization: Bearer then gets a 401 it cannot explain, and an OAuth client reads that 401 as an expired token and re-runs sign-in forever.

From plugin 9.1.0 and MCP server 8.4.0, Respira's clients send the credential a second time in X-Respira-Authorization, and the plugin uses that copy when a REST request arrives with no credential at all. Nothing to configure. The fallback never overwrites a real Authorization header (a staging site's HTTP password keeps working), it stands aside when X-Respira-API-Key is present, and it accepts only Bearer followed by a Respira key or access token, so it cannot log anyone in through application passwords or another plugin.

• The Authorization self-test in Respira > Troubleshoot reports whether the copy arrives, with the status stripped_fallback_ok for a server that eats Authorization but passes Respira's header.
• To turn the fallback off: define( 'RESPIRA_DISABLE_AUTH_FALLBACK', true ); in wp-config.php, or the respira_allow_auth_fallback filter from a must-use plugin.
• On a plugin older than 9.1.0 the answer is still the .htaccess rule that passes Authorization through, or the ?rest_route= address; see rest_route fallback.

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

The agent cannot find a schema block, a tracking pixel or a meta tag

That text is usually not in the page builder content: an SEO plugin or a header code setting prints it when the page renders, so a search of the page's elements finds nothing. With plugin 9.1.11 or newer, ask the agent to use respira_find_in_page, which searches the published HTML, head included, and names the snippet or setting that holds the text.

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:

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

Helpful resources

• Introduction
• Installation
• Configuration
• Usage Guide
• Prompts & Examples
• API Reference
• Release History

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.