The Salesforce DX MCP Server: driving your org from Claude, Cursor, and VS Code

Ask an AI coding assistant to “deploy this Apex class and run its tests” against a Salesforce org, and until recently you had two bad options. You could let it shell out to the sf CLI and hope it didn’t guess a destructive flag, or you could copy-paste the output of each command back and forth like a human relay. Neither is how you’d want an autonomous tool touching an org that has production data in it.

Salesforce’s answer is the Salesforce DX MCP Server — an official Model Context Protocol server, published on npm as @salesforce/mcp, that exposes org operations as structured, named tools any MCP client can call. Point Claude Code, Cursor, or VS Code with Copilot at it, and the assistant can deploy metadata, run tests, query records, create scratch orgs, and assign permission sets — through a governed interface, against orgs you’ve explicitly allowlisted, instead of improvising CLI incantations. This post is what the server actually gives you, how the security model works, how it differs from the two other MCP stories Salesforce is telling, and the sharp edges — because a chunk of the most interesting tools are still labeled NON-GA and off by default.

Three different “Salesforce MCP” things — don’t conflate them

Salesforce is using the letters MCP in at least three places, and they solve different problems for different people. Before you wire anything up, get these straight:

• The DX MCP Server (this post). A local developer tool. It runs on your machine, wraps Salesforce DX operations, and lets your AI IDE act on your orgs. The consumer is a coding assistant; the job is building and shipping metadata.
• Agentforce as an MCP client. The opposite direction — a runtime agent in your org reaching out to external MCP servers to use their tools. That’s the subject of connecting Agentforce to an MCP server, and it’s about production agents, not your laptop.
• Agentforce Vibes. Salesforce’s own agentic coding product with its own IDE and workflow, which we covered in Agentforce Vibes pricing and licensing. Vibes is a packaged coding agent; the DX MCP Server is plumbing you attach to whatever assistant you already use.

The DX MCP Server is the bring-your-own-assistant option. If your team already lives in Claude Code or Cursor and doesn’t want to adopt a second IDE, this is the piece that connects the assistant you have to the org you deploy to.

What it actually is: TypeScript over DX, not a CLI wrapper

Mechanically, the server is a Node process you start with npx. It speaks MCP to the client over stdio and, on the other side, performs Salesforce DX operations. The startup command carries its own security posture in the flags:

npx -y @salesforce/mcp --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,data,testing

Two things are load-bearing there and worth reading slowly. --orgs is the allowlist of which authenticated orgs the server may touch. --toolsets is which groups of tools you’re enabling. Neither has a permissive default you can forget about — --orgs is required, and if you don’t name toolsets you get a minimal set. The design intent is least privilege, expressed as launch arguments.

Crucially, the server does not want your secrets in a prompt. You authorize orgs the normal DX way — sf org login web, or SFDX: Authorize an Org from the VS Code command palette — before the server runs, and the server reuses those existing authenticated connections. As the docs put it plainly: “You must explicitly authorize the orgs on your computer before the MCP server can access them.” The AI client never sees a username, password, or token; it sees tool names and the results of calling them. That boundary is the whole reason to prefer this over letting an assistant type sf commands with credentials floating around in the shell.

Configuring it in your client

The wiring is a few lines of JSON in whatever config file your client reads. For Claude Code, that’s .mcp.json at the project root:

{
  "mcpServers": {
    "salesforce-dx": {
      "command": "npx",
      "args": [
        "-y", "@salesforce/mcp",
        "--orgs", "DEFAULT_TARGET_ORG",
        "--toolsets", "orgs,metadata,data,testing"
      ]
    }
  }
}

For VS Code or Cursor, the same server block goes in .vscode/mcp.json (Cursor reads an equivalent mcp.json). Restart the client, and the tools show up in its tool list. That’s the entire install: no separate daemon, no account provisioning, no listener port. It piggybacks on the DX authorization you already have.

The --orgs value is where you decide blast radius. The accepted values are worth memorizing because they’re your safety rail:

• DEFAULT_TARGET_ORG — only your project’s default org.
• DEFAULT_TARGET_DEV_HUB — only your default Dev Hub (for scratch-org operations).
• <username or alias> — a specific named org, nothing else.
• ALLOW_ALL_ORGS — every org you’ve authorized. The docs flag this one with “Use this value with caution,” and you should read that as “do not point this at a machine that has production credentials sitting in it.”

The conservative pattern for a developer working in a scratch-org flow is --orgs DEFAULT_TARGET_ORG,DEFAULT_TARGET_DEV_HUB and nothing more. You physically cannot fat-finger a deploy into production if production isn’t in the allowlist.

The toolsets: what the assistant can do

Tools are grouped into toolsets you enable by name, so you only expose what a given session needs. The core toolset (things like get_username and resume_tool_operation) is always on. The ones you’ll reach for most:

• orgs — org lifecycle: create_scratch_org, create_org_snapshot, list_all_orgs, open_org, delete_org.
• metadata — the deploy loop: deploy_metadata and retrieve_metadata.
• data — run_soql_query, so the assistant can inspect real records instead of guessing at your schema.
• testing — run_apex_test and, notably, run_agent_test, which executes Agentforce agent tests in your org.
• users — assign_permission_set, the single most common “why can’t it see anything” fix.
• devops — a full set of DevOps Center operations: checkout_devops_center_work_item, commit_devops_center_work_item, create_devops_center_pull_request, detect_devops_center_merge_conflict, promote_devops_center_work_item, and more.
• code-analysis — runs Salesforce Code Analyzer: run_code_analyzer, list_code_analyzer_rules, and rule authoring.

There are also expert toolsets — lwc-experts, aura-experts, mobile — that carry dozens of guidance and scaffolding tools for building Lightning Web Components, migrating Aura, and generating mobile LWC features. Those are powerful and also the fastest way to blow past your model’s context window, which is exactly why they’re opt-in rather than bundled.

Here’s what a real interaction looks like once it’s wired up. You tell the assistant: “Deploy the LWC and Apex in force-app to my scratch org, run the Apex tests, and if anything fails, show me the failing assertions.” Under the hood the assistant calls deploy_metadata, then run_apex_test, reads the structured results, and either reports green or pulls the failing test output for you to look at — no CLI transcript, no copy-paste, and every operation scoped to the one org you allowlisted. Pair it with a disciplined sandbox and scratch-org strategy and the assistant becomes a genuinely useful pair for the inner-loop grind.

The security model, honestly

The MCP-over-a-tool pattern is safer than letting an assistant run raw shell commands, but “safer” is not “safe by assumption,” and there are three things to be deliberate about.

The allowlist is the perimeter, so respect it. The entire safety story rests on --orgs not including anything you’d mind an autonomous tool writing to. If you routinely authorize your production org on your dev machine for support work, do not run the server with ALLOW_ALL_ORGS. Keep a separate config for production access, or better, keep production credentials off the machine the assistant runs on.

Deploys and deletes are real actions. deploy_metadata changes an org. delete_org destroys a scratch org. An assistant that decides, mid-task, to “clean up” is calling real operations. Most clients let you require confirmation before a tool runs — turn that on for the write tools. This is the same least-privilege posture we argue for with any agent that can act: the defense isn’t trusting the model to behave, it’s making sure the tools it can reach can’t do damage you haven’t approved.

Prompt injection reaches further than you think. If the assistant reads a SOQL result, a metadata file, or a code comment that contains adversarial instructions, and that assistant also holds deploy_metadata, you have a path from untrusted content to an org write. Treat query results and repo contents as untrusted input to the model, and keep the write toolsets out of any session that’s also ingesting data you don’t control.

None of this is unique to Salesforce’s server — it’s the ambient risk of giving an LLM real tools. But a deploy tool pointed at an org is more consequential than most, so the discipline matters more.

The NON-GA problem: read the labels

Here’s the caveat that will actually trip you up. A meaningful number of the server’s tools are marked NON-GA — not yet generally available — and they are off by default. To use them you have to launch with:

npx -y @salesforce/mcp --orgs DEFAULT_TARGET_ORG \
  --toolsets metadata,testing --allow-non-ga-tools

That flag is a deliberate speed bump, and you should treat it as one. NON-GA tools can change behavior, change their names, or disappear between releases; building a team workflow that depends on one is building on sand. The server itself and its core deploy/test/query loop are stable enough to rely on, but before you standardize any tool across a team, check whether it’s GA in the version you’re pinning. The whole surface moves fast — Salesforce is adding toolsets release over release — so “it worked in a demo last month” is not the same as “it’s stable.”

A second practical note: enabling all toolsets to “see everything” is a trap. The expert toolsets alone add well over a hundred tools, and Salesforce’s own guidance is that enabling them all can overwhelm the model’s context. Enable the toolsets a given task needs and no more. Your assistant will reason better with ten relevant tools than with a hundred it has to wade through.

Where it fits in a real workflow

The DX MCP Server is at its best in the inner loop — the write-deploy-test cycle a developer runs dozens of times a day. Let the assistant handle the mechanical parts (deploy, run the tests, query a record to confirm the data shape, assign the permission set it forgot) while you stay on the design. It is not a replacement for a governed release pipeline. When a change is ready to move toward production, it should go through the same release-management maturity ladder your team already uses — and the devops toolset’s DevOps Center tools are how the assistant participates in that pipeline rather than routing around it.

The honest framing: this server makes an AI assistant a competent junior developer on your org — fast at the rote work, needs a leash on the consequential actions, and occasionally confidently wrong about your schema until it runs a run_soql_query and finds out. Give it the leash (a tight --orgs allowlist, write-tool confirmations, GA tools only for anything shared) and it earns its place in the loop. Skip the leash and you’ve handed deploy access to something that reads its instructions from whatever text happens to be in context.

What to actually do

Install @salesforce/mcp in whatever assistant your team already uses, not a new one. Authorize your scratch org and Dev Hub through the normal DX login, and launch the server with --orgs DEFAULT_TARGET_ORG,DEFAULT_TARGET_DEV_HUB — never ALLOW_ALL_ORGS on a machine that can see production. Enable only the toolsets the work needs — orgs, metadata, data, testing, users cover most inner-loop development. Turn on your client’s confirm-before-run for the write tools. Leave --allow-non-ga-tools off unless you’re deliberately experimenting, and never build a shared team workflow on a NON-GA tool. Do that, and you get a real productivity gain — the assistant handles the deploy-test-query grind against exactly the orgs you allowed and nothing else.

The broader point is that MCP is quietly becoming the seam between AI tools and Salesforce in both directions — assistants reaching into your orgs to build, and agents reaching out of your orgs to act. The DX MCP Server is the developer-facing half of that story, and it’s the lowest-risk place to get fluent in how governed tool access actually behaves before you wire an autonomous agent to anything that matters.

Understanding the basics

What is the Salesforce DX MCP Server?

It’s an official Model Context Protocol server, published on npm as @salesforce/mcp, that exposes Salesforce DX operations — deploying metadata, running Apex and agent tests, running SOQL queries, creating and deleting scratch orgs, assigning permission sets, and DevOps Center actions — as structured tools any MCP-capable AI client (Claude Code, Cursor, VS Code with Copilot) can call. It runs locally, reuses the org authorizations you’ve already set up through the Salesforce CLI, and never exposes credentials to the AI client.

How does it keep an AI assistant from touching production?

Through the required --orgs flag, which allowlists exactly which authorized orgs the server may access. You can scope it to your default org, your default Dev Hub, or a specific named org; the permissive ALLOW_ALL_ORGS value is documented with an explicit “use with caution” warning. If production isn’t in the allowlist, the assistant cannot reach it. Combine that with your client’s confirm-before-run setting on write tools like deploy_metadata, and keep production credentials off the machine the server runs on.

How is it different from Agentforce Vibes and from Agentforce’s MCP support?

Three different things. The DX MCP Server is local plumbing that connects any AI coding assistant you already use to your orgs. Agentforce Vibes is Salesforce’s own packaged agentic coding IDE. Agentforce acting as an MCP client is the runtime opposite — a production agent in your org reaching out to external MCP servers to use their tools. The DX MCP Server is for building; the Agentforce MCP client is for running.

---

Wiring an AI assistant into your Salesforce development loop and want the org allowlist, toolset scoping, and release path set up so it speeds delivery without touching production by accident? Talk to us — building governed, AI-assisted delivery workflows is exactly the work we do.