Install sf-intelligence and answer your first org question

Last updated 2026-07-23

Track 1 - try it now, no org needed

Want to see it work before pointing it at your own org? One command serves a built-in synthetic demo org ("Verdant Energy," a fictional solar installer) over MCP - fully offline, no auth, no sf CLI required.

claude mcp add --transport stdio --scope user sf-intelligence-demo -- npx -y sf-intelligence demo

Then ask it things like:

› What happens when I save a Project?
› What breaks if I delete Invoice__c.Amount__c?
› Why can't an Installer see an Invoice?
› Which Apex has governor-limit risk?

The first run builds the demo vault in a few seconds (cached under ~/.sf-intelligence/demo); every run after is instant. Nothing leaves your machine.

track 2 - connect your own org

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 compact tool roster (SFI_TOOL_PROFILE=core)

Every sfi.* tool schema is advertised by default - most MCP hosts pay a real token tax for that (~250 KB of tools/list JSON) if they don't defer tool definitions. Set SFI_TOOL_PROFILE=core on the server process to advertise only an 18-tool core roster instead - orientation, resolve/route, the universal graph reads, and a catalog gateway (list_analyses / describe_analysis / run_analysis) that reaches every other tool with byte-identical output. Nothing is removed - a non-advertised tool still works if called directly; only what's advertised at boot changes. Add it to the config block above:

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

Default stays full - this is purely opt-in. See the configuration reference for the full tool-profile details.

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.

Install as a Claude Code plugin

The MCP registration above gets you the sfi.* tools. Installing sf-intelligence as a Claude Code plugin additionally gets you 26 skills that auto-activate on Salesforce vocabulary - no need to remember tool names - and 5 slash commands (/sfi-onboard guided first run, /sfi-init, /sfi-refresh, /sfi-status, /sfi-field-audit) that wrap the sfi CLI. Install it from this repo's marketplace:

/plugin marketplace add PranavNagrecha/Salesforce-Intelligence
/plugin install sf-intelligence@sf-intelligence

Run /reload-plugins (or restart Claude Code) to pick it up in the current session; /plugin list confirms it's installed and enabled. The plugin manifest registers the same MCP server shown above, so once it's installed you don't need a separate claude mcp add step.