Troubleshooting WowInvoice MCP Connections

Use this guide to resolve common WowInvoice MCP connection, authentication, permission and document-operation issues.

The Connection Panel Asks You to Save an Access Mode

Navigate to WooCommerce → WowInvoice → AI Tools → Access Mode.

Select Read only, Manage or Full access, click Save access mode and check Current Access.

Selecting Off disables MCP and revokes existing WowInvoice OAuth connections.

A System Readiness Check Is Not Ready

Check the component identified under System Readiness:

  • WordPress 6.9+ and Abilities API.
  • WooCommerce.
  • WordPress MCP Adapter.
  • Pretty permalinks.

Resolve the reported issue and recheck System Readiness before connecting.

Your AI Assistant Cannot Reach Your Website

Confirm that:

  • Your WowInvoice MCP server address is correct.
  • Your website is publicly accessible over HTTPS for remote connections.
  • Your hosting provider, firewall, security plugins or website password protection are not blocking the connection.

The WowInvoice endpoint is /wp-json/winv/mcp. Do not substitute another plugin’s MCP endpoint.

Remote connectors cannot access localhost. For local websites, use a compatible desktop or CLI application that can reach your website.

Sign-In or Authorization Fails

Sign in using a WordPress administrator account and check the error returned by your AI application.

Confirm that you are using the correct authentication method:

ConnectionAuthentication
Remote web connectorOAuth with WordPress sign-in and approval
Desktop bridgeWordPress username and application password
CLI connectionUsername and application password encoded in Base64

If the application was disconnected or MCP access was set to Off, save an enabled access mode and authorize the OAuth connection again.

A Desktop App Cannot Start the Local Bridge

Check that:

  • Node.js is installed and npx is available.
  • You are using the current configuration from WowInvoice.
  • Your website address, WordPress username and application password are correct.
  • OAUTH_ENABLED is set to "false".

Save the configuration and restart the application.

VS Code requires a separate configuration in .vscode/mcp.json using servers and type: stdio. The generic desktop configuration uses mcpServers.

CLI Authentication Fails

Generate your Base64 credentials using your actual WordPress username and application password separated by a colon.

Check that:

  • The encoded value contains no line breaks.
  • The Authorization header starts with Basic followed by a space and the encoded value.
  • Your application password has not been revoked.
  • The MCP server address and saved access mode are correct.

Restart the application after changing its configuration.

Treat Base64 credentials as passwords when sharing diagnostic information.

A Document Operation Is Refused

Confirm that you are using a WordPress administrator account and check Current Access and the Tools table.

OperationRequired Access
Document, template, settings and order lookupsRead only or higher
Generate a PDFManage or Full access
Private previews, configuration changes, snapshot resets, issued originals and print recordsFull access

Additional OAuth consent and licensing requirements may apply.

Read the returned error and verify the order ID, document type and requested operation. Not every refusal is caused by insufficient permissions.

A Document Cannot Be Generated

  1. Use get-document-overview to check the document type and publication status.
  2. Use check-document-setup to inspect readiness for the intended order.
  3. Confirm the order is eligible and the generation action has been approved.
  4. Review the returned error before retrying.

PDF generation can issue a document number. Avoid repeatedly requesting generation without understanding the previous result.

A Snapshot Reset Produces Unexpected Results

Resetting a document snapshot makes the next PDF use current settings while retaining its issued number.

Confirm the affected order and document type before repeating the operation.

Do not assume that resetting a snapshot deletes the document, changes its issued number or generates a new PDF.

A Draft Remains Unpublished After Applying Changes

Applying approved changes through apply-settings-change does not publish a draft.

Review the exact draft, confirm publication and use publish-document. Publication runs readiness checks and sample rendering.

An Issued Original Is Missing

The view-issued-document tool reports missing retained originals without regenerating them.

A preview or newly generated PDF does not establish that the original is retained.

A Print Record Does Not Match Physical Printing

The mark-document-printed tool records or corrects a staff assertion for one exact document.

Confirm that physical printing occurred before approving the record.

This operation does not send a document to a printer.

No MCP Activity Is Shown

Click Refresh under Recent MCP Tool Activity.

The activity panel retains up to 100 records from the last 30 days.

Run the Confirm your AI can read this store prompt and inspect the assistant’s actual tool response alongside the activity panel.

Contact WowInvoice Support

If the issue persists, provide:

  • WordPress, WooCommerce, WowInvoice and MCP Adapter versions.
  • AI application and connection method.
  • Current MCP access mode.
  • Tool name and exact error message.
  • Order ID and document type, where relevant.
  • Relevant diagnostic information with sensitive details removed.

Never share application passwords, access tokens, Base64 credentials, private document links or unnecessary customer information in public support requests.