Local Claude Code agents use remote MCP file tools instead of local filesystem, causing partial deploys

[hellno]

Problem

When both the local Jack MCP server (stdio, jack mcp serve) and the remote Jack MCP server (HTTP, mcp.getjack.org) are connected in Claude Code, agents use the remote update_file / read_project_file tools for file operations instead of the built-in Read/Edit/Write tools + jack ship.

This causes real failures — not just inefficiency.

Real-world failure case

An agent working in local Claude Code on a project with 3 files:

1. Used mcp__claude_ai_jack__update_file to stage index.ts and stadtundland.ts
2. Forgot to stage wbm.ts — the third file imported by index.ts
3. Deployed via remote MCP — deploy succeeded but the worker 500s on every request because wbm.ts is missing
4. Remote MCP server then disconnected, leaving agent completely stuck
5. Agent's final advice: "just run jack ship from your terminal" — which would have uploaded all files correctly from the start

This class of bug cannot happen with local deploy (jack ship / mcp__jack__deploy_project) because it uploads the entire directory contents, not individual staged files.

Root causes

1. Both servers register as "jack"

Local MCP → mcp__jack__* tools. Remote MCP → mcp__claude_ai_jack__* tools. To the LLM, these look like variants of the same server.

2. Remote file tools overlap with built-in tools

The remote MCP exposes update_file, read_project_file, list_project_files, list_staged_changes — designed for terminal-less environments (claude.ai web, Claude Desktop) where there's no local filesystem. In Claude Code, these overlap with built-in Read/Edit/Write which are faster, more reliable, and work with the full local directory.

3. "Prefer MCP" guidance is too broad

CLAUDE.md says: "CRITICAL: When Jack MCP is connected, always prefer mcp__jack__* tools over CLI commands or wrangler". This was written assuming only the local MCP. Agents interpret remote MCP tools as matching this guidance too.

Proposed fixes

A. Update remote MCP tool descriptions (low effort, immediate)

Prefix update_file and read_project_file descriptions with:

"REMOTE-ONLY: Only use when you do NOT have local filesystem access (e.g. claude.ai web). If you have built-in Read/Edit/Write tools, use those + deploy_project instead."

B. Narrow CLAUDE.md guidance (low effort, immediate)

Change the "prefer MCP" instruction to scope it to cloud operations only:

"Prefer mcp__jack__* tools for deployment, database, log, and service operations. For file editing, always use built-in Read/Edit/Write tools — never update_file or read_project_file."

C. Detect dual connection in jack mcp install (medium effort)

When installing the local MCP config, check if a remote jack entry already exists. Warn the user and offer to remove it, since local MCP + local filesystem covers all remote MCP functionality.

D. Rename remote server to jack-cloud (low effort, breaking)

Remote tools become mcp__jack_cloud__*, clearly distinguishing them from local mcp__jack__*. Breaking change for existing remote MCP users.

E. Conditionally hide file tools on remote MCP (high effort, cleanest)

Detect whether the client has local filesystem access and exclude update_file/read_project_file/list_project_files/list_staged_changes from the tool list. MCP protocol doesn't have standard capability negotiation yet, so this would need a custom mechanism.

Recommended approach

Combine A + B + C:

• Immediately update remote tool descriptions and CLAUDE.md guidance (A + B)
• Add dual-connection detection to jack mcp install (C)

Relevant files

• apps/cli/src/lib/mcp-config.ts — local MCP registration, writes to ~/.claude.json
• apps/mcp-worker/src/server.ts — remote MCP tool definitions
• apps/mcp-worker/src/tools/source.ts — update_file, read_project_file implementations
• apps/cli/src/mcp/tools/index.ts — local MCP tool definitions
• apps/cli/src/mcp/resources/index.ts — agents://context resource with "prefer MCP" guidance
• CLAUDE.md — project-level "prefer MCP" instruction