Install & first run

1. Prerequisites

You need two things on the machine that runs your MCP client. Versions are minimums.

Node.js 20+

npx, which launches the server, ships with Node. Install Node.js 20 LTS if this reports an older version.

node --version   # v20.x or later

Salesforce CLI (sf), authenticated

sfi refresh shells out to sf project retrieve, so you need a working sf CLI logged in to your target org. Confirm connectedStatus is "Connected":

sf --version
sf org list --json        # connectedStatus must be "Connected"
# not connected? re-authenticate:
sf org login web --alias my-org-alias

A Salesforce DX project repo

sf-intelligence vaults a per-org repo — the directory that holds your sfdx-project.json and force-app/. The vault (org-kb/) lives next to that source. No DX repo yet?

sf project generate --name my-org-repo
cd my-org-repo

2. Install — register the MCP server

Claude Code — from your DX repo, register it project-scoped (writes a .mcp.json at the repo root, which you can commit so your team shares it):

claude mcp add --transport stdio --scope project sf-intelligence -- npx -y sf-intelligence mcp

Use --scope user to make it available in every project on your machine, or --scope local (the default) for just this project, private to you.

Claude Desktop, or any other MCP client — add this block to the client's MCP config (Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restart the client:

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

Optional: a shorter sfi command

npx -y sf-intelligence … works without installing anything, but it's verbose and re-checks the registry each run. A global install gives you a short sfi command for setup; or add it to the repo and call it via npx (which resolves the local copy, no re-download):

npm install -g sf-intelligence    # global: gives you `sfi`
# …or, local to the repo:
npm install sf-intelligence       # adds it to the repo
npx sf-intelligence --version     # resolves the local copy

3. Verify the install

In a session with your MCP client, confirm the server connected:

• Claude Code — run /mcp. sf-intelligence should be listed as connected.
• Any client — ask the model to run sfi.health_check. A healthy envelope (or degraded "no vault" — expected before your first refresh) means it's wired up correctly.

4. First-run setup

From your DX repo. The first refresh is read-only: it retrieves metadata and builds the local knowledge base — it never deploys or mutates Salesforce data.

sfi init                               # create org-kb/, record the org alias
sfi refresh --target-org my-org-alias  # retrieve metadata, build the vault
sfi status                             # freshness, source-tree hash, counts
sfi doctor                             # checks sf CLI, vault, auth, graph + fixes

The first refresh runs sf project retrieve then the extractor → renderer → graph-import pipeline; it takes a few minutes on a typical sandbox, and later refreshes are incremental. No global install? Prefix each command with npx -y sf-intelligence. The vault (org-kb/) is local to the repo — most teams gitignore it.

5. Ask anything the vault can answer

From whatever MCP client you registered, ask in plain language:

› What fields does the Account object have?
› What breaks if I delete CustomField:Account.Industry__c?
› Why can't the Standard User profile see Opportunities?
› Give me a tour of this org.

See the capability map and the full tool reference for everything it can answer.

6. Keeping the vault fresh

The vault is a point-in-time snapshot; the live org keeps changing. Two tools tell you when to re-pull, so a stale answer is never presented as current:

• sfi.health_check reports a freshness block — the vault's age, a stale flag, and a plain-language nudge once it's more than a week old (advisory only).
• sfi.live_drift_check compares the vault's recorded fields against a live describe of an object you name, reporting what's drifted. It reads the org, so it needs the opt-in live plane.

When either flags drift, run sfi refresh --target-org my-org-alias (or /sfi-refresh) to re-pull and rebuild.

7. Troubleshooting

Anything not on this table — run sfi doctor; it checks the sf CLI, the vault, target-org auth, freshness, and the graph file, and prints an actionable fix for each problem.

Configuration, live data & the plugin

Vault answers are offline by default. To enable the read-only live plane (record counts, samples, org limits), set environment variables, or wire up multiple orgs, see the configuration reference.

Running it as a Claude Code plugin? The same operations are slash commands — /sfi-onboard (guided first run), /sfi-init, /sfi-refresh, /sfi-status — and the coaching skills auto-activate when Salesforce vocabulary appears.