Graphtia documentation · reference
Agent integration troubleshooting
Diagnose detection, configuration, verification, workspace approval and result-currentness problems.
The client is not detected
Confirm that the supported client is installed for the current desktop user and available to your Explorer version.
Open the client once so it can create its normal configuration.
Return to Explorer and refresh the AI agents panel.
For an unlisted client, use Universal MCP instead of treating it as a native adapter.
Connected, but tools are missing
Fully restart the host or start the new session described by its guide.
Run Test connection in Explorer.
If Explorer reports Needs repair, choose Repair and review the planned Graphtia-owned changes.
Do not delete the host configuration or unrelated MCP servers.
Identity or approval is required
Identity and workspace permission are separate. Complete the identity handshake when requested, then approve the intended registered workspace in Explorer. Approval remains read-only and does not authorize code changes.
The wrong workspace appears
Check the project name and root registered in Explorer.
Ask the agent to list registered candidates instead of guessing.
Select the workspace explicitly and reuse its project ID during the investigation.
For project-scoped native setup, connect from the exact registered root.
Results are stale, partial or truncated
Confirm the indexed revision and currentness state before using the result.
Refresh or rescan the workspace after source changes.
Narrow the query before increasing limits.
Treat missing static edges as an investigation result, not proof that runtime behavior is impossible.
Disconnect safely
Use Disconnect in Explorer for a native integration. It removes Graphtia-owned entries and guidance while preserving other host settings. For Universal MCP, remove only the server entry you created in that client.
After an Explorer update or expired session
If Explorer asks for sign-in, reconnect the intended account first. A saved workspace approval is separate from account and product authorization. Session expiry does not mean your commercial plan became Free.
An already running client can retain its previous MCP process or configuration. Start the fresh client session recommended by its integration card and run Test connection. Configuration present, connection verified and an authorized workspace query are different checks.
If access was denied, expired or revoked, review the intended client and workspace in Explorer. Repeated background retries must not replace your decision. A persistent grant is revocable and does not automatically follow a replaced project folder.