assign_permission_set
Assign a permission set to one or more org users.
LABSCO SUMMARY
The scratch-org cycle survives being driven by something other than your hands.
Create an org from a snapshot or definition file, deploy the project into it, run Apex tests with coverage, delete it — the whole loop is covered, and a long job can be picked back up by id, which is the step that usually strands an agent halfway through a deploy. Worth knowing before you wire it up: the delete tool is destructive enough that its own instruction is to confirm with the user first.
What it is
Salesforce's own server over the CLI's operations, organised into toolsets you switch on by name: org resolution, scratch orgs and snapshots, metadata deploy and retrieve, SOQL, permission sets and Apex tests, with further sets for LWC and Aura work, code analysis, mobile, DevOps Center and Apex performance.
What you get
- Org resolution that works out which username or alias an operation should target, separately for the default target org and the default Dev Hub
- Scratch orgs created from a definition file, edition, duration or an existing snapshot, aliased and set as default, then deleted when the work is done
- Metadata deployed from and retrieved into your local project, with the file set calculated for you when you do not name one
- SOQL run against an org, optionally through the Tooling API
- Apex tests run by class, method or suite at a test level you choose, with code coverage
- Permission sets assigned to org users, including on another user's behalf, and an org opened in the browser at a named metadata file
- A long-running job resumed by its id — a metadata deploy, a scratch org creation, a snapshot — instead of started again
- Only the tools you asked for: --toolsets names the groups, --tools adds individual ones, and a core set is always on
- Tools that are not yet generally available held back until --allow-non-ga-tools says otherwise, and telemetry switched off with --no-telemetry
Requirements
Node.js, an org you are already authorized to from this machine, and a local Salesforce project directory for the metadata and Apex tools. The --orgs flag is mandatory and decides what the server may touch: name usernames or aliases to pin it, or pass DEFAULT_TARGET_ORG, which resolves per call and follows whatever your default org happens to be at the time. ALLOW_ALL_ORGS exists and hands over everything you are authorized to. Scratch orgs and snapshots additionally need a Dev Hub. Enabling every toolset puts more than sixty tools in front of the model, which is why the toolsets exist. Apache-2.0.
Setup effort
One command — npx -y @salesforce/mcp@latest --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,data,users --tools run_apex_test --allow-non-ga-tools
USE CASES
01
Standing up a clean org to try something in
Create the scratch org from a definition file or an existing snapshot, alias it, and make it the default for what follows.
02
Getting your project into the org and tested
Deploy the metadata, then run the Apex tests with coverage — the test scope taken from what you are working on if you do not name it.
03
Picking up a change someone made in the org
Retrieve the metadata into the local project rather than reconstructing it by hand.
04
Answering a question about the data
Run the SOQL against the org — through the Tooling API when the question is about metadata rather than records.
05
Recovering from a deploy that took too long
Resume the operation by its id instead of starting it again and racing the first one.
06
Giving a tester the access they are missing
Assign the permission set to the users who need it, without opening setup.
12 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
create_org_snapshot
Creates a new snapshot of an org
AGENT INSTRUCTIONS:
Example usage: Create a snapshot called 07042025 create a snapshot called 07042025 with the description, "this is a snapshot for commit 5b1a09b1743 - new login flow working" create a snapshot of my MyScratch in myDevHub
create_scratch_org
Creates a scratch org with the specified parameters.
AGENT INSTRUCTIONS:
Example usage: Create a scratch org create a scratch org with the definition file myDefinition.json that lasts 3 days create a scratch org aliased as MyNewOrg and set as default and don't wait for it to finish
delete_org
Deletes specified salesforce org.
AGENT INSTRUCTIONS: ALWAYS confirm with the user before deleting an org
Example usage: Can you delete my org Can you delete MyAliasedOrg Can you delete test-fe2n4tc8pgku@example.com
deploy_metadata
Deploy metadata to an org from your local project.
AGENT INSTRUCTIONS: If the user doesn't specify what to deploy exactly ("deploy my changes"), leave the "sourceDir", "ignoreConflicts" and "manifest" params empty so the tool calculates which files to deploy.
EXAMPLE USAGE: Deploy changes to my org Deploy this file to my org Deploy the manifest Deploy X metadata to my org Deploy X local files to my org and ignore any conflicts between the local project and org Deploy X to my org and run A,B and C apex tests.
get_username
Intelligently determines the appropriate username or alias for Salesforce operations.
WHEN TO USE THIS TOOL:
- When uncertain which org username a user wants for Salesforce operations.
To resolve the default org username, set the defaultTargetOrg param to true and defaultDevHub to false. To resole the default devhub org username, set the defaultTargetOrg param to false and defaultDevHub to true. If it's not clear which type of org to resolve, set both defaultTargetOrg and defaultDevHub to false to an allow-listed org username available.
list_all_orgs
Lists all configured Salesforce orgs.
AGENT INSTRUCTIONS: DO NOT use this tool to try to determine which org a user wants, use #get_username instead. Only use it if the user explicitly asks for a list of orgs.
Example usage: Can you list all Salesforce orgs for me List all Salesforce orgs List all orgs
open_org
Open a Salesforce org in the browser.
You can specify a metadata file you want to open.
resume_tool_operation
Resume a long running operation that was not completed by another tool.
AGENT INSTRUCTIONS: Use this tool to resume a long running operation.
EXAMPLE USAGE: Resume the metadata deploy job 0Af1234567890 Resume the deployment and wait for 10 minutes Resume the deployment to my org Resume scratch org creation Resume job 2SR1234567890 Resume agent tests Resume org snapshot with ID 0OoKa000000XZAbKAO Report on my org snapshot
retrieve_metadata
Retrieve metadata from an org to your local project.
AGENT INSTRUCTIONS: If the user doesn't specify what to retrieve exactly ("retrieve my changes"), leave the "sourceDir", "ignoreConflicts", and "manifest" params empty so the tool calculates which files to retrieve.
EXAMPLE USAGE: Retrieve changes Retrieve changes from my org Retrieve this file from my org Retrieve the metadata in the manifest Retrieve X metadata from my org Retrieve X metadata from my org and ignore any conflicts between the local project and org
run_apex_test
Run Apex tests in an org.
AGENT INSTRUCTIONS: If the user doesn't specify what to test, take context from the currently open file This will ONLY run APEX tests, NOT agent tests, lightning tests, flow tests, or any other type of test.
this should be chosen when a file in the 'classes' directory is mentioned
EXAMPLE USAGE: Run tests A, B, C. Run the myTestMethod in this file Run this test and include success and failures Run all tests in the org. Test the "mySuite" suite asynchronously. I’ll check results later. Run tests for this file and include coverage What are the results for 707XXXXXXXXXXXX
run_soql_query
Run a SOQL query against a Salesforce org.
BEFORE YOU INSTALL
What to know first
Tools you get
12 tools when we connected; the project documents 89. The example config enables only the orgs, metadata, data and users toolsets plus core and run_apex_test. Use --toolsets all for every tool; non-GA tools such as create_scratch_org and delete_org also need --allow-non-ga-tools.
Requires
- Node.js 20 or newer (the server runs through npx)
- A Salesforce org you have authorized on this machine: org login web in the Salesforce CLI, or SFDX: Authorize an Org in VS Code
Where it runs
All 4 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y @salesforce/mcp@latest --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,data,users --tools run_apex_test --allow-non-ga-toolsMCP Clients
VS Code
VS CODE · JSON
{
"servers": {
"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"
]
}
}
}Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"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"
]
}
}
}Cline, Cursor
JSON
{
"mcpServers": {
"Salesforce DX": {
"command": "npx",
"args": [
"-y",
"@salesforce/mcp@latest",
"--orgs",
"DEFAULT_TARGET_ORG",
"--toolsets",
"orgs,metadata,data,users",
"--tools",
"run_apex_test",
"--allow-non-ga-tools"
]
}
}
}
