Why does running uvx in the terminal work but the MCP client still shows disconnected?

GUI apps like Claude Desktop launch with a minimal environment that doesn't include your shell's PATH. Even if uvx works in your terminal, the client can't find it unless you use the full absolute path in the config (e.g. /Users/you/.local/bin/uvx).

I ran pip install agentic-store-mcp and it fixed the issue. Why?

The package was likely installed inside a project virtual environment that the MCP client couldn't see. Installing without an active venv puts it in the system Python, which is reachable by the client. Using uvx instead avoids this entirely — it manages its own isolated environment automatically.

How do I force uvx to use the latest version of agentic-store-mcp?

Run: uvx --no-cache agentic-store-mcp --list. The --no-cache flag bypasses the local cache and pulls the latest release from PyPI.

Why does the server disconnect after a few minutes of inactivity?

This is controlled by the client, not the server. Some clients time out idle MCP connections. Restarting the client reconnects it. If it's constant, check that uvx can reach PyPI and that no firewall is blocking outbound connections.

Can I use a specific Python venv instead of uvx?

Yes. Point the config's command at the full path to your venv's Python binary (e.g. /path/to/venv/bin/python) and set args to ["-m", "agentic_store_mcp", "--modules", "code,data"].

MCP Server Troubleshooting

Two categories cover 95% of setup issues. Expand the one that matches your symptom.

Config file locations

Claude Desktop

macOS/Linux~/Library/Application Support/Claude/claude_desktop_config.json

Windows%APPDATA%\Claude\claude_desktop_config.json

Cursor

macOS/Linux~/.cursor/mcp.json

Windows%USERPROFILE%\.cursor\mcp.json

Windsurf

macOS/Linux~/.codeium/windsurf/mcp_config.json

Windows%USERPROFILE%\.codeium\windsurf\mcp_config.json

VS Code

macOS/Linux.vscode/mcp.json or settings.json

Windows.vscode\mcp.json or settings.json

Full setup per client → Client Setup

Still stuck?

→ Open an issue on GitHub → Email [email protected]

Common questions