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:
| Connection | Authentication |
|---|---|
| Remote web connector | OAuth with WordPress sign-in and approval |
| Desktop bridge | WordPress username and application password |
| CLI connection | Username 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
npxis available. - You are using the current configuration from WowInvoice.
- Your website address, WordPress username and application password are correct.
OAUTH_ENABLEDis 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
Basicfollowed 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.
| Operation | Required Access |
|---|---|
| Document, template, settings and order lookups | Read only or higher |
| Generate a PDF | Manage or Full access |
| Private previews, configuration changes, snapshot resets, issued originals and print records | Full 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
- Use
get-document-overviewto check the document type and publication status. - Use
check-document-setupto inspect readiness for the intended order. - Confirm the order is eligible and the generation action has been approved.
- 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.