Salesforce MCP in VS Code + Copilot: setup, and why your server silently does not load

The one mistake that breaks most setups

Most MCP guides are written for Claude or Cursor. Their config files use a top-level mcpServers key. VS Code’s .vscode/mcp.json uses servers (VS Code MCP configuration reference).

If you paste mcpServers into .vscode/mcp.json:

• the file is still valid JSON,
• VS Code registers zero servers,
• no error dialog appears.

VS Code does underline the key in the editor. That is easy to miss if you created the file somewhere else.

Newer VS Code builds also document a portable .mcp.json file at the project root that does use mcpServers. The .vscode/mcp.json file with servers is the route that works on every version since 1.102, so this guide uses it.

Before you start

You need:

1. VS Code 1.102 or later with GitHub Copilot signed in.
2. Node.js 20 or later. Check with node --version.
3. The Salesforce CLI, logged in to your org. Check with sf org list. If needed, run sf org login web --alias my-org.
4. A Salesforce DX project for that org, open in VS Code.

Set it up

1. Build the local copy of your org’s metadata. From your project folder, run:

   Terminal

   npx -y sf-intelligence init --target-org my-org
   npx -y sf-intelligence refresh --target-org my-org
   

   This retrieves metadata with the Salesforce CLI and stores it in an org-kb folder in your project. It reads only. Nothing is written to the org.

2. Create .vscode/mcp.json in the project and paste:

   JSON

   {
     "servers": {
       "sf-intelligence": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "sf-intelligence", "mcp", "--vault", "${workspaceFolder}/org-kb"],
         "cwd": "${workspaceFolder}"
       }
     }
   }
   

   VS Code fills in ${workspaceFolder} for you. Keep --vault. Without it, the server looks for org-kb in whatever folder it was started from, which may not be your project.

3. Start the server. Open the Command Palette and run MCP: List Servers. Select sf-intelligence and choose Start. A workspace server follows your Workspace Trust setting.

4. Check that it is running. In MCP: List Servers, the server should show as running. If not, choose Show Output to see why.

5. Check that Copilot sees the tools. Open Copilot Chat in Agent mode. Select the Configure Tools button in the chat input. You should see sf-intelligence with tools such as sfi_route_question, sfi_what_happens_on_save and sfi_safe_to_delete_field. VS Code swaps the dots in tool names for underscores and logs a warning for each. That is cosmetic.

6. Ask a question. For example: “What happens when I save an Opportunity?” The answer should name the triggers, flows and rules it found.

If you only see sfi_setup_status

That is setup mode, not a failure. The server started but did not find your metadata. Ask Copilot: “What do you need from me?” The tool reports where it looked and which command to run. Usually step 1 was skipped, or --vault points to the wrong folder. Restart the server after fixing it.

User-level setup (every project)

To make the server available in all workspaces, run MCP: Open User Configuration. ${workspaceFolder} has nothing to point at there, so use a full path:

{
  "servers": {
    "sf-intelligence": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sf-intelligence", "mcp", "--vault", "/absolute/path/to/my-org/org-kb"]
    }
  }
}

Keep the server name hyphenated (sf-intelligence). VS Code groups server instructions on underscores, so sf_intelligence gets grouped wrongly.

Running it next to the Salesforce DX MCP server

sf-intelligence explains your org and never changes it. The Salesforce DX MCP server can deploy, retrieve and run tests. They work side by side in one file. The DX block below is copied from Salesforce’s README:

{
  "servers": {
    "sf-intelligence": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sf-intelligence", "mcp", "--vault", "${workspaceFolder}/org-kb"],
      "cwd": "${workspaceFolder}"
    },
    "Salesforce DX": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp", "--orgs", "DEFAULT_TARGET_ORG",
               "--toolsets", "orgs,metadata,data,users",
               "--tools", "run_apex_test", "--allow-non-ga-tools"]
    }
  }
}

Be aware: Salesforce says @salesforce/mcp reaches end of life on November 2, 2026 (announcement). For a full comparison, see Salesforce MCP servers compared.

Windows notes

Still stuck? Run npx -y sf-intelligence doctor in your project. It checks Node, the Salesforce CLI, the metadata folder and org login, and prints a fix for each problem.

With sf-intelligence: a first question to try

Once the tools show up, try a question that needs your org’s real metadata. On the built-in demo org, ask: “What breaks if I delete Invoice__c.Amount__c?” Copilot can call sfi_safe_to_delete_field. The answer is blocking:

Each blocker is a named component you can open. The same answer lists the categories it could not check, such as reports and Lightning pages, so a short list never reads as “nothing else uses it”.

"verdict": "blocking",
"reasoning": [
  { "category": "apex",    "verdict": "blocking", "examples": [{ "id": "ApexClass:PaymentService" }] },
  { "category": "formula", "verdict": "blocking", "examples": [{ "id": "CustomField:Invoice__c.Balance__c" }] },
  { "category": "rollup",  "verdict": "blocking", "examples": [{ "id": "CustomField:Project__c.Total_Invoiced__c" }] }
]

Try it on the demo org

No Salesforce org or CLI login needed. Add this to .vscode/mcp.json in any folder:

{
  "servers": {
    "sf-intelligence-demo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sf-intelligence", "demo"]
    }
  }
}

VS Code runs npx -y sf-intelligence demo for you. It is a server that waits for VS Code to talk to it, so there is nothing to run in a terminal. The first start downloads the package and builds the demo, so it takes a little longer. Later starts are faster. Then ask: “What happens when I save a Project?”