Start with a dummy note and reproduce the smallest failing action. Check the tool’s version and account before changing configuration.
MCP tools do not appear
- Check node --version and npx --version in your terminal. The desktop client must also be able to find them.
- Confirm the command is npx and the arguments are -y, privatenote-mcp.
- Use a local stdio connection. A remote-only MCP client cannot start this server.
- Restart the MCP connection after changing configuration. Inspect the client’s MCP error log for startup failures.
A local file is refused
Use an absolute path inside the project or PRIVATENOTE_MCP_ALLOWED_ROOTS. A server started in your home directory or / needs explicit roots. Resolve the intended file’s real location; paths that escape allowed roots are refused.
Do not relax the boundary by granting the whole filesystem. SSH keys, cloud credentials, and session files remain blocked.
Confirmation expired or the file changed
A confirmation is single-use and expires after five minutes. Changing the file after preview invalidates the approved bytes. Ask the agent to prepare a new preview, inspect it, and approve again.
A failed confirmation attempt can consume the token. Repeating the old confirmationId is not a retry strategy.
Sign-in is incomplete
Approve the browser page opened by the tool. For MCP, call sign_in again after approval. Check whoami or the extension’s account display. A website login alone does not establish the tool’s app session.
If a feature remains unavailable, confirm that the signed-in account has the required plan and, for open notifications, a verified email.
CLI will not print a link
When stdout is piped or captured, explicitly pass --output-url-only, or use --json --force-stdout for structured output. Do not combine --json and --output-url-only. Store any resulting URL as sensitive data.
Selection or clipboard problems
In Chrome, test on an ordinary webpage rather than a settings page or the Web Store. Check chrome://extensions/shortcuts for shortcut conflicts. If automatic copying is unavailable, use Copy link.
In the editor, select text before invoking Share as PrivateNote. Try the sidebar composer to distinguish a selection issue from a connection problem.
The recipient cannot open the note
- Copy the complete link, including the #fragment. A missing key cannot be recovered by the server.
- Check whether the note was already revealed, expired, or revoked.
- For password-protected notes, confirm the separately supplied password.
- For recipient verification, use the configured recipient email address.
- Create a fresh dummy note to distinguish access lifecycle behavior from an installation problem.
Get help
Use PrivateNote contact for support. Developer tools are available in the public repository. Include versions and sanitized reproduction steps; leave out full note URLs, session files, and secret contents.