Sudhakar

Posted on Oct 27

The 'Disconnected' Dilemma: A Mac User's Journey to Connecting the Gemini CLI and Salesforce MCP server

#salesforce #gemini #cli #macos

🧩 The "Disconnected" Dilemma: A Mac User’s Journey to Connecting the Gemini CLI and Salesforce

Connecting the Gemini CLI to Salesforce felt like unlocking a superpower — using natural language to query orgs, analyze code, and deploy metadata, all from the terminal.

But what I thought would be a 10-minute setup turned into a multi-step troubleshooting puzzle.

The main villain?

🔴 salesforce - Disconnected

This is the story of that journey, the problems I faced on Mac (Apple Silicon), and the “Aha!” moment that finally fixed it.

If you’re seeing that same red dot, this guide is for you.

🎯 The Goal & The Setup

The Goal: Configure the Gemini CLI to use the Salesforce MCP Server.

The Machine: A Mac with Apple Silicon (M1/M2/M3).

🧰 The Key Software

Gemini CLI – The AI agent.
Salesforce CLI (sf) – Installed and authorized with a default org.
npm / npx – Used to run the MCP server package.

🧪 The Troubleshooting Timeline

Phase 1: The “By the Book” Attempt (And the First Failure)

I started by following the developer documentation. It suggested using the Salesforce CLI directly to start the server.

My ~/.gemini/settings.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "sf",
      "args": ["force", "mcp:server:start"]
    }
  }
}

The Result:
I launched Gemini and ran:

bash /mcp list

The Output:

✗ salesforce: ... - Disconnected

The command seemed logical but clearly wasn’t establishing the persistent connection Gemini needed.

Phase 2: Finding the Right Package (And a New Mystery)

After more research, I found that the standard way to run the server is by using the dedicated npm package @salesforce/mcp.

My ~/.gemini/settings.json (Attempt 2):

json { "mcpServers": { "salesforce": { "command": "npx", "args": [ "-y", "@salesforce/mcp@latest", "--orgs", "DEFAULT_TARGET_ORG", "--toolsets", "orgs,metadata,code-analysis" ] } } }

The Result:
After restarting Gemini and running /mcp list:

✗ salesforce: npx -y @salesforce/mcp ... - Disconnected

This was frustrating. The command was correct, the package official, and the org authorized. So why was it still disconnecting?

Phase 3: The “Aha!” Moment (Testing the Command Directly)

We realized we were assuming the command itself was failing.
But what if Gemini was the one failing to connect?

The Test:
Run the command directly in the terminal:

bash npx -y @salesforce/mcp@latest --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,code-analysis

The Result:

Salesforce MCP Server v0.23.4 running on stdio

✅ The server worked perfectly.
The Salesforce CLI authorization and npx command were fine.
The issue wasn’t Salesforce — it was how Gemini was spawning the process.

Phase 4: The Mac Silicon Clue (Environment Mismatch)

Here’s where the Apple Silicon clue came in.

When Gemini (a Node.js app) spawns a child process (like npx), it doesn’t always inherit the full $PATH from your interactive shell (like .zshrc).
This happens frequently when using version managers like nvm or fnm.

Gemini was trying to run npx, but its isolated environment couldn’t find the command.
The process exited instantly, and Gemini reported Disconnected.

Phase 5: The Fix (Absolute Path to the Rescue)

If the $PATH is unreliable, don’t rely on it.
Tell Gemini exactly where npx lives.

Step 1: Find the Path

bash which npx

Example output:

/usr/local/bin/npx

Yours might differ, such as /Users/<your-name>/.nvm/versions/node/v20.x.x/bin/npx.

Step 2: Update settings.json

Final, working version:

json { "mcpServers": { "salesforce": { "command": "/usr/local/bin/npx", "args": [ "-y", "@salesforce/mcp", "--orgs", "DEFAULT_TARGET_ORG", "--toolsets", "orgs,metadata,code-analysis", "--tools", "deploy_metadata,retrieve_metadata" ] } } }

Phase 6: Success!

After saving the file and relaunching Gemini, I ran:

bash /mcp list

The Output:

✓ salesforce: /usr/local/bin/npx -y @salesforce/mcp ... (stdio) - Connected

It finally connected 🎉

⚙️ Now What? How to Use Your Connected Server

Getting Connected is just the first step.
Next, you need to use the available tools through natural language.

You don’t explicitly tell Gemini which tool to use — it infers that based on your prompt.

💬 How to Prompt Gemini

Use descriptive keywords that align with the tools (deploy_metadata, retrieve_metadata, code-analysis, etc.).

Examples:

Retrieve metadata:

“Please retrieve the metadata for the Account object from my default Salesforce org.”

Deploy metadata:

“Take the file src/classes/MyNewClass.cls and deploy it to Salesforce.”

Code analysis:

“Analyze the Apex class MyController.cls for any security vulnerabilities or performance issues.”

Each time, Gemini asks for confirmation and shows the exact command it plans to execute — proof that the MCP server is being used.

📚 Appendix: Installation & Useful Links

🧩 1. Running via npx (Standard Method)

bash npx -y @salesforce/mcp@latest --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,data,users

What it does:
Downloads and runs the latest MCP package, then removes it.
Perfect for testing.

🧰 2. Installing Globally (Optional Troubleshooting Step)

If npx is unreliable, you can install globally:

bash npm install -g @salesforce/mcp

This ensures a stable global package version.
Not required for most users, but helpful if npx caching fails.

🔗 Related Documentation

💡 Key Lessons for Future Users

"Disconnected" = "Instant Exit" → The server process likely failed to start.
Test Commands Directly → Always run the command + args outside Gemini first.
Mac/Linux Users (especially with nvm/fnm): Use the absolute path to npx or other executables.
Windows Users: Use "cmd" with "/c" in settings.json, e.g.:

json "command": "cmd", "args": ["/c", "npx", ...]

🏁 Conclusion:
The “Disconnected” message wasn’t a bug — it was a clue.
Understanding how Gemini spawns its processes revealed the real issue: environment inheritance.
With the absolute path fix, the Gemini–Salesforce bridge now runs perfectly.

DEV Community