MCP troubleshooting

Quick checks

1. Confirm that Weave is running.
2. Confirm that command is the absolute path generated by Weave.
3. Check that ZX_RUNTIME_DATA_ROOT, ZX_MCP_CLIENT_FINGERPRINT, and ZX_MCP_BRIDGE_SECRET are present.
4. Match the outer format to the Agent: Codex uses TOML, Claude commonly uses mcpServers, and VS Code uses servers.
5. Fully restart the Agent after saving configuration.
6. Confirm that the client still has a grant for the target knowledge base.

Common errors

Symptom	Resolution
The weave Server is missing	Check configuration location and syntax, then fully restart the Agent.
RUNTIME_NOT_RUNNING	Open Weave and ensure the configuration came from the current installation and data directory.
MCP client is not paired	The fingerprint or secret is missing, wrong, or revoked. Pair again.
Connected but no knowledge bases appear	The client has no active knowledge-base read grant.
Search works but writes fail	Read-only pairing works. Grant the matching capability separately in Weave.
A write never executes	Inspect pending confirmations; the token may have expired or the payload may have changed.
stdio or JSON errors	Do not use a shell wrapper that writes logs to stdout.
The path breaks after running from a DMG	Move Weave to Applications and generate the configuration again.

Collect diagnostic information

When reporting a problem, include the Weave version, operating system, Agent and version, the MCP status shown by the Agent, and whether the failure occurs during connection, search, or write confirmation.

Never send a real ZX_MCP_BRIDGE_SECRET.

macOS logs are stored at:

~/Library/Logs/cloud.longde.zhixi.desktop/Weave.log