Salesforce MCP Server

What is it

Salesforce MCP Server is a Model Context Protocol (MCP) server that enables AI assistants to interact with Salesforce organizations. It provides a set of tools that allow AI models to execute Apex code, query data, describe objects, and manage Salesforce org connections through the Salesforce CLI.

NPM Package: @advanced-communities/salesforce-mcp-server

Installation

Prerequisites

• Node.js (v22 or higher)
• Salesforce CLI (sf) installed and configured
• At least one authenticated Salesforce org

Option 1: NPM Installation (Recommended)

The easiest way to install Salesforce MCP Server is directly from NPM using npx:

npx @advanced-communities/salesforce-mcp-server

This command will:

• Download the latest version from NPM
• Run the server directly without manual installation
• Automatically handle all dependencies

Benefits of NPM Installation:

• ✅ No manual building required
• ✅ Always get the latest stable version
• ✅ Automatic dependency management
• ✅ Easy updates with npm update
• ✅ No need to clone the repository

Option 2: MCP Bundle (MCPB) - One-Click Installation

For a fully managed installation experience:

1. Download the latest salesforce-mcp-server.mcpb file from the releases page
2. Double-click the .mcpb file to install
3. The extension will be automatically configured in your AI client
4. All dependencies will be managed automatically

Option 3: Manual Installation - Build from source

For development or customization:

1. Clone the repository: git clone https://github.com/advancedcommunities/salesforce-mcp-server.git
2. Navigate to the directory: cd salesforce-mcp-server
3. Install and build: npm install && npm run build
4. The server will be available at build/index.js

Add MCP Configuration to your client

To be able to run the MCP Server – you need a client. The client can be any AI app which supports the MCP protocol, such as:

• Claude Desktop
• Claude Code
• Codex CLI
• VS Code Copilot
• Cursor

Use it with Claude Desktop

1. Install Claude Desktop from Anthropic.

2. Open it up and authenticate to Claude.

3. Edit your config file at:

   • Mac: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows: C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\Claude\\claude_desktop_config.json

   If you can’t find the file. Open Claude Desktop, open the Settings menu, go to the Developer section and click Edit Config inside the servers section. Open and edit this file using the instructions below.

4. Add the following to your config file under the "mcpServers" key:

   {
       "mcpServers": {
           "salesforce-mcp-server": {
               "command": "npx",
               "args": ["@advanced-communities/salesforce-mcp-server"]
           }
       }
   }
   

   With environment variables (optional):

   {
       "mcpServers": {
           "salesforce-mcp-server": {
               "command": "npx",
               "args": ["@advanced-communities/salesforce-mcp-server"],
               "env": {
                   "READ_ONLY": "true",
                   "ALLOWED_ORGS": "dev,qa,staging"
               }
           }
       }
   }
   

5. Restart Claude Desktop (quit & re-open the app). Now you are able to use the MCP in the Claude Desktop.

Use it with Claude Code

1. Install Claude Code.

2. Open it up and authenticate to Claude by runnung the claude command in your terminal.

3. Execute one of the following commands in your terminal:

   Basic installation (local scope - default):

   claude mcp add salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server
   

   User scope installation (recommended for global access):

   claude mcp add --scope user salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server
   

   With environment variables:

   # Read-only mode (local scope)
   claude mcp add salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server -e READ_ONLY=true
   
   # Read-only mode (user scope)
   claude mcp add --scope user salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server -e READ_ONLY=true
   
   # Restrict to specific orgs (user scope)
   claude mcp add --scope user salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server -e ALLOWED_ORGS=dev,qa,staging
   
   # Both restrictions (user scope)
   claude mcp add --scope user salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server -e READ_ONLY=true -e ALLOWED_ORGS=production
   
   # Open orgs and records in the client's built-in browser (user scope)
   claude mcp add --scope user salesforce-mcp-server npx @advanced-communities/salesforce-mcp-server -e USE_CLIENT_BROWSER=true
   

   Note: By default, Claude Code installs MCP servers in local scope (current directory). Use --scope user to install globally for all projects.

Use it with Codex CLI

The Codex CLI can be configured to leverage MCP servers by defining an mcp_servers section in ~/.codex/config.toml. It is intended to mirror how tools such as Claude and Cursor define mcpServers in their respective JSON config files, though the Codex format is slightly different since it uses TOML rather than JSON, e.g.:

[mcp_servers.salesforce-mcp-server]
command = "npx"
args = ["@advanced-communities/salesforce-mcp-server"]

# Optional: Add environment variables
[mcp_servers.salesforce-mcp-server.env]
READ_ONLY = "true"
ALLOWED_ORGS = "dev,qa,staging"
USE_CLIENT_BROWSER = "true"

Use it with VS Code

1. In VS Code, open the Command Palette by pressing Command + Shift + P or Ctrl + Shift + P.
2. Type “MCP Add”, select the MCP: Add Server option.
3. Select Command(stdio) option.
4. Put the npx @advanced-communities/salesforce-mcp-server into the command input.
5. For MCP Server Id put salesforce-mcp-server.
6. Choose either Global or Workspace installation option.
7. (Optional) To add environment variables, manually edit the VS Code settings:
   • Open settings.json (Preferences: Open Settings (JSON))
   • Add environment variables to your MCP server configuration:

   "mcp.servers": {
     "salesforce-mcp-server": {
       "command": "npx",
       "args": ["@advanced-communities/salesforce-mcp-server"],
       "env": {
         "READ_ONLY": "true",
         "ALLOWED_ORGS": "dev,qa"
       }
     }
   }
   

Use it with Cursor

1. Install Cursor

2. Open it up and create your account and connect to a model provider

3. Open Cursor -> Settings -> Cursor Settings -> Mcp

4. Add new global MCP Server

5. This will drop you into an editor of the JSON config. Fill in a value for the key salesforce-mcp-server:

   {
       "mcpServers": {
           "salesforce-mcp-server": {
               "command": "npx",
               "args": ["@advanced-communities/salesforce-mcp-server"]
           }
       }
   }
   

   With environment variables (optional):

   {
       "mcpServers": {
           "salesforce-mcp-server": {
               "command": "npx",
               "args": ["@advanced-communities/salesforce-mcp-server"],
               "env": {
                   "READ_ONLY": "true",
                   "ALLOWED_ORGS": "production,staging"
               }
           }
       }
   }
   

   If there are any existing keys under mcpServer, don’t delete them. Add salesforce-mcp-server to the end.

6. Save the file. Go back to the Cursor Settings tab. You should see salesforce-mcp-server listed and the dot should go green.

7. Open Composer view and toggle from normal to agent (small text on bottom of input)

8. You can now use tools

Configuration

The server supports the following environment variables for access control:

• READ_ONLY=true - Prevents execution of Apex code (anonymous execution and tests)
• ALLOWED_ORGS=ALL - Allow access to all orgs (default)
• ALLOWED_ORGS=org1,org2,org3 - Restrict access to specific org aliases
• USE_CLIENT_BROWSER=true - Hand org and record URLs to the AI client’s built-in browser instead of launching your desktop browser (default: false)

When ALLOWED_ORGS is set, the list_connected_salesforce_orgs tool will only show orgs that match the allowed list.

Org Identifier Masking

Org identifiers are always masked before they reach the AI client; there is nothing to configure. list_connected_salesforce_orgs returns:

• Usernames partially masked, e.g. [email protected] becomes ja***@ex***.com (sandbox suffixes such as .uat are kept as the last label)
• Org IDs with only the 00D prefix and last 4 characters visible, e.g. 00D***********dEAA
• Instance URLs with the scheme and Salesforce domain suffix kept and the My Domain part masked, e.g. https://acme.my.salesforce.com becomes https://ac***.my.salesforce.com. Sandbox My Domains mask the company and sandbox names separately, e.g. https://acme--uat.sandbox.my.salesforce.com becomes https://ac***--ua***.sandbox.my.salesforce.com. Suffixes such as .develop.my.salesforce.com, .scratch.my.salesforce.com and .lightning.force.com are kept; for unknown hosts only the leftmost label is masked. Paths and query strings are dropped.
• A note field reminding the assistant to use aliases as targetOrg, since masked usernames cannot be used to target an org

Aliases, isDevHub and apiVersion are not masked. Production/sandbox/scratch categorization is done on the raw values before masking.

The default org is reported by alias only. get_default_org, the defaultOrg field of get_server_permissions and the salesforce://permissions resource return the alias of the CLI’s target-org, even when it’s configured as a username (the org’s first alias is used). If the default org has no alias, they return a masked username and get_default_org asks you to set an alias. Usernames, org IDs and instance URLs of the default org are never returned. Tools still run against the real default org.

When a tool runs against the default org, the targetOrg it echoes back (in text and structured output), its access-denied message and the prompts’ text use the same alias-only form, never the raw username.

Other places identifiers are masked:

• login_into_org, logout, open (desktop browser mode) and display_user mask the username, org ID and instance/login URLs in the CLI result. open in desktop mode also drops the path and login token from the returned URL, since the browser is already open. In client browser mode, open and open_record still return the real pre-authenticated URL, because the client’s browser needs it.
• The salesforce://org/{alias}/metadata resource and the org_health_check prompt return masked usernames, org IDs and instance URLs.
• Usernames listed in ALLOWED_ORGS are masked in the tool’s permissionMessage, in the server description, in access-denied messages, and in the allowedOrgs value returned by get_server_permissions and the salesforce://permissions resource.
• Error messages from list_connected_salesforce_orgs and MCP log notifications (for example the CLI commands the server runs) are scrubbed of usernames, org IDs and URLs.
• Resource alias completions suggest aliases only.

Orgs without an alias can’t be targeted by the assistant, so set one first:

sf alias set [email protected]

Use Client’s Built-in Browser

Some AI clients ship their own browser. Set USE_CLIENT_BROWSER=true to keep Salesforce inside that browser instead of popping open your desktop one. Verified with the Claude Cowork and ChatGPT desktop apps; it also works with any client that has a browser tool attached, such as the Chrome DevTools or Playwright MCP servers.

{
    "mcpServers": {
        "salesforce-mcp-server": {
            "command": "npx",
            "args": ["@advanced-communities/salesforce-mcp-server"],
            "env": {
                "USE_CLIENT_BROWSER": "true"
            }
        }
    }
}

In MCPB installs the same option appears as the Use Client’s Built-in Browser checkbox in the extension settings.

What changes when it is enabled:

• open and open_record no longer launch a browser. They return a pre-authenticated Salesforce URL (generated with sf org open --url-only) together with openInClientBrowser: true, so the assistant can navigate to it with its own browser tool.
• The server advertises the mode in its MCP instructions, which clients surface to the assistant, so it knows to open the returned URL rather than print it.
• open and open_record accept forceSystemBrowser: true to launch your desktop browser for that one call.
• Passing browser or privateMode to open counts as asking for your desktop browser, so the org opens there even while the mode is active — neither option means anything to the client’s browser.
• login_into_org is unaffected — the Salesforce CLI OAuth flow always uses your desktop browser.

The returned URL contains a single-use Salesforce login token minted by Salesforce (/services/oauth2/singleaccess) and valid for up to one minute. It logs whoever opens it into the org as you, so treat it like a credential: it is meant for the client’s browser tool, not for chat logs or third parties.

Open one link before asking for the next. Salesforce caches the token for the life of that minute, so URLs generated back to back can carry the same token with different destinations, and navigating several in quick succession may drop the browser on a login page instead of the record you asked for. Once the first link has signed the browser in, that session carries the login — ordinary Salesforce URLs work from then on without a token.

Client browser mode is reported by the get_server_permissions tool and the salesforce://permissions resource as useClientBrowser.

Default Org

All tools that interact with a Salesforce org accept an optional targetOrg parameter. When targetOrg is not provided, the server automatically resolves the default org from your Salesforce CLI configuration.

To set a default org:

sf config set target-org 

To check which org is currently set as default:

sf config get target-org

When a default org is configured, you can use any tool without specifying targetOrg — the server will use the default automatically. If no targetOrg is provided and no default org is configured, the tool will return an error asking you to either provide targetOrg or set a default.

You can check the current default org via the get_server_permissions tool, which includes its alias in its response.

Permission Examples

Read-only access to all orgs:

{
    "mcpServers": {
        "salesforce-mcp-server": {
            "command": "npx",
            "args": ["@advanced-communities/salesforce-mcp-server"],
            "env": {
                "READ_ONLY": "true"
            }
        }
    }
}

Full access to specific orgs only:

{
    "mcpServers": {
        "salesforce-mcp-server": {
            "command": "npx",
            "args": ["@advanced-communities/salesforce-mcp-server"],
            "env": {
                "ALLOWED_ORGS": "dev,qa,staging"
            }
        }
    }
}

Read-only access to specific orgs:

{
    "mcpServers": {
        "salesforce-mcp-server": {
            "command": "npx",
            "args": ["@advanced-communities/salesforce-mcp-server"],
            "env": {
                "READ_ONLY": "true",
                "ALLOWED_ORGS": "production,prod-backup"
            }
        }
    }
}

You can check the current permission settings using the get_server_permissions tool.

How to use it

Once the SF MCP Server is configured in your AI client, you can interact with Salesforce using natural language. The AI assistant will have access to 47 powerful tools, 5 guided workflow prompts, 5 browsable resource types, and structured logging with progress reporting:

Available Tools

1. List Connected Salesforce Orgs

View all Salesforce orgs currently authenticated with the Salesforce CLI. Usernames, org IDs and instance URLs are masked (see Org Identifier Masking).

Example prompts:

• “Show me all connected Salesforce orgs”
• “List my available Salesforce organizations”
• “Which Salesforce orgs can I access?”

2. List Objects in an Org

Retrieve all standard and custom objects available in a specific Salesforce org.

Example prompts:

• “List all custom objects in my dev org”
• “Show me all objects in the production org”
• “What custom objects exist in sandbox1?”

3. Describe an Object

Get detailed metadata about a specific Salesforce object, including fields, relationships, and properties.

Example prompts:

• “Describe the Account object in my org”
• “Show me all fields on the Custom_Object__c in dev org”
• “What are the relationships on the Contact object?”

4. Execute Apex Code

Run anonymous Apex code directly in a Salesforce org and see the debug output.

Example prompts:

• “Execute this Apex in my dev org: System.debug(‘Hello World’);”
• “Run a query in Apex to count all Accounts”
• “Execute Apex code to create a test Account record”

5. Query Records

Execute SOQL queries and retrieve results in JSON format.

Example prompts:

• “Query the first 10 Accounts from my org”
• “Find all Contacts with email domain ‘@example.com’”
• “Get Opportunities closed this month with amount over $10,000”
• “Query all Case records created today”

6. Query Records to File

Execute SOQL queries and save results to CSV or JSON files.

Example prompts:

• “Export all Leads to a CSV file”
• “Save all Opportunities from Q4 2024 to a JSON file”
• “Create a CSV export of Accounts with their related Contacts”

7. Run Apex Tests

Execute Apex test classes with various options including test level and code coverage.

Example prompts:

• “Run all tests in my dev org”
• “Execute the AccountTriggerTest class with code coverage”
• “Run all local tests excluding managed packages”

8. Get Apex Test Results

Retrieve results from a previous asynchronous Apex test run.

Example prompts:

• “Get the results of test run ID 707xx0000000001”
• “Show me the code coverage from the last test run”

9. Get Apex Code Coverage

Get code coverage information for a Salesforce org.

Example prompts:

• “What’s the overall code coverage in my org?”
• “Show code coverage from the latest test run”

10. Generate Apex Class

Generate metadata source files for a new Apex class.

Example prompts:

• “Generate a new Apex class called AccountHelper”
• “Create an Apex controller class named MyCustomController”
• “Generate a batch class called DataCleanupBatch in the classes directory”

11. Generate Apex Trigger

Generate metadata source files for a new Apex trigger.

Example prompts:

• “Generate a trigger called AccountTrigger for the Account object”
• “Create a before insert trigger for the Contact object”
• “Generate an after update trigger for MyCustomObject__c”

12. List Apex Logs

Fetch and list Apex debug logs from the org.

Example prompts:

• “Show me all Apex debug logs in my dev org”
• “List the recent debug logs from production”
• “Get the IDs of debug logs in sandbox”

13. Get Apex Log

Fetch specific Apex debug logs or recent logs from the org.

Example prompts:

• “Get the debug log with ID 07L…”
• “Show me the last 5 debug logs from my org”
• “Fetch the most recent debug log from production”

14. Login to Salesforce Org

Authenticate and login to a Salesforce org via web browser.

Example prompts:

• “Login to a new production org with alias ‘prod’”
• “Connect to a sandbox with alias ‘dev-sandbox’”

15. Get Server Permissions

Check current server permission settings.

Example prompts:

• “Show me the current server permissions”
• “What orgs am I allowed to access?”

16. Run Code Analyzer

Analyze your code with configurable rules to ensure good coding practices.

Example prompts:

• “Run code analyzer on all Apex classes”
• “Analyze my Lightning Web Components for security issues”
• “Check PMD rules on the force-app directory”

17. List Code Analyzer Rules

List available rules for code analysis.

Example prompts:

• “Show me all available code analyzer rules”
• “List security-related code analysis rules”
• “What ESLint rules are available?”

18. Scanner Run

Scan a codebase with various security and quality rules using multiple engines.

Example prompts:

• “Scan all Apex files for security vulnerabilities”
• “Run PMD and ESLint scanners on my codebase”
• “Check for retire-js vulnerabilities in my JavaScript files”
• “Scan with high severity threshold and save results to CSV”

19. Scanner Run DFA

Run Salesforce Graph Engine for data flow analysis to identify complex security issues.

Example prompts:

• “Run data flow analysis on my Apex controllers”
• “Check for SOQL injection vulnerabilities using Graph Engine”
• “Perform path-based security analysis on all Apex classes”
• “Run DFA with pilot rules enabled”

20. Assign Permission Set

Assign permission sets to one or more org users.

Example prompts:

• “Assign the DreamHouse permission set to the admin user in my dev org”
• “Grant CloudHouse and AppBuilder permission sets to [email protected]”
• “Assign multiple permission sets to a list of users in sandbox”

21. Assign Permission Set License

Assign permission set licenses to org users.

Example prompts:

• “Assign the Sales Cloud license to [email protected]”
• “Grant Service Cloud permission set license to multiple users”
• “Assign Platform Event license to the admin user”

22. Display User

Display information about a Salesforce user including profile, org ID, and access details.

Example prompts:

• “Show me information about the admin user in my org”
• “Display user details for [email protected]”
• “Get the profile and access token for the current user”

23. List Metadata

List metadata components and properties of a specified type.

Example prompts:

• “List all CustomObject components in my org”
• “Show me all Dashboard components in the Sales folder”
• “Get all EmailTemplate metadata with API version 60.0”
• “List Layout components and save to a file”

24. List Metadata Types

Display details about all metadata types enabled for your org.

Example prompts:

• “Show me all available metadata types in my org”
• “List metadata types for package.xml creation”
• “Get all enabled metadata types with API version 60.0”
• “Display metadata types and save to file for reference”

25. Logout

Log out of a Salesforce org, removing stored authentication.

Example prompts:

• “Logout from my dev org”
• “Remove authentication for sandbox1”
• “Logout from all connected orgs”

26. Open

Open a Salesforce org in your browser. With USE_CLIENT_BROWSER=true it returns a pre-authenticated URL for the client’s built-in browser instead; pass forceSystemBrowser: true to launch your desktop browser anyway.

Example prompts:

• “Open my dev org in Chrome”
• “Open the Lightning Experience page in my sandbox”
• “Open my org in private/incognito mode”
• “Open a Visualforce page /apex/MyPage in production”
• “Open my FlexiPage in Lightning App Builder”
• “Open my dev org in my own browser, not yours”

27. Open Record

Open a specific Salesforce record in the browser. With USE_CLIENT_BROWSER=true it returns a pre-authenticated URL for the client’s built-in browser instead; pass forceSystemBrowser: true to launch your desktop browser anyway.

Example prompts:

• “Open record 001XX0000XXXXX in my dev org”
• “Navigate to Account record 001… in production”
• “Show me the Contact record 003… in the browser”

28. Create Record

Create a new record in a Salesforce org using the REST API.

Example prompts:

• “Create a new Account with Name ‘Acme Corp’ and Type ‘Customer’”
• “Insert a Contact record with FirstName ‘John’ and LastName ‘Doe’”
• “Create a Case with Subject ‘Technical Issue’ and Priority ‘High’”
• “Add a new Lead with Company ‘Tech Startup’ and Email ‘[email protected]’”

29. Update Record

Update an existing record in a Salesforce org using the REST API.

Example prompts:

• “Update Account 001XX… to set BillingCity to ‘San Francisco’”
• “Change the Status of Opportunity 006XX… to ‘Closed Won’”
• “Update Contact 003XX… with Phone ‘(555) 123-4567’”
• “Modify Case 500XX… to set Priority to ‘Critical’”

30. Delete Record

Delete a record from a Salesforce org using the REST API.

Example prompts:

• “Delete the Account record 001XX…”
• “Remove Contact 003XX… from the org”
• “Delete Lead record 00QXX…”
• “Remove the test Case record 500XX…”

31. Package Install

Install or upgrade a package version in a Salesforce org.

Example prompts:

• “Install package 04tXXXXXXXXXXXXXX in my dev org”
• “Upgrade the package with ID 04t… in production with 10 minute wait time”
• “Install a protected package with key ‘mykey123’ in sandbox”
• “Install package and compile only package Apex code”
• “Upgrade unlocked package and deprecate removed components”

32. Package Uninstall

Uninstall a second-generation package from a Salesforce org.

Example prompts:

• “Uninstall package 04tXXXXXXXXXXXXXX from my dev org”
• “Remove the package with alias ‘old_package’ from production”
• “Uninstall package and wait 5 minutes for completion”
• “Remove package with spaces in alias from sandbox”

33. Schema Generate Tab

Generate metadata source files for a new custom tab on a custom object.

Example prompts:

• “Create a tab for MyObject__c with icon 54 in the tabs directory”
• “Generate a custom tab for Invoice__c object with icon 25”
• “Add a navigation tab for Customer__c with icon 75 in force-app/main/default/tabs”
• “Create a tab for Product__c custom object with default icon”

34. Search Records

Execute SOSL text-based searches across multiple objects. This is the primary tool for finding records that mention or contain specific text across your Salesforce org.

Example prompts:

• “Search for ‘Anna Jones’ in all Name fields”
• “Find records containing ‘Acme’ across all objects”
• “Search for phone number ‘415-555-1234’ in Contact and Lead”
• “Find all records mentioning our competitor ‘Acme Corp’ across Accounts, Opportunities, and Cases”
• “Execute SOSL: FIND {Smith} IN ALL FIELDS RETURNING Contact, Lead”

35. Generate Lightning Component

Generate Lightning Web Components (LWC) or Aura components with configurable templates and output directories.

Example prompts:

• “Generate a Lightning Web Component called AccountList”
• “Create an Aura component named ContactForm in the components directory”
• “Generate an LWC with analyticsDashboard template called SalesMetrics”
• “Create a Lightning component MyCustomView with default template”

36. Deploy Metadata to Org

Deploy metadata components to a Salesforce org with various configuration options including test execution.

Example prompts:

• “Deploy all metadata from force-app directory to my dev org”
• “Validate deployment to production with all tests but don’t save (dry run)”
• “Deploy specific Apex classes matching ‘Account*’ pattern to sandbox”
• “Deploy using package.xml manifest with RunLocalTests”
• “Deploy metadata and run specific test classes: TestClass1, TestClass2”

37. Get Default Org

Get the alias of the current default target org configured in the Salesforce CLI. This is the org used automatically when no targetOrg is specified. Only the alias is returned; if the default org has no alias, a masked username is returned with a prompt to set one (sf alias set =).

Example prompts:

• “What is my default Salesforce org?”
• “Show me the current default target org”
• “Which org am I connected to by default?”

38. Set Default Org

Set the default target org for the Salesforce CLI. Once set, all tools will use this org when no targetOrg is specified.

Example prompts:

• “Set my default org to dev-sandbox”
• “Change the default target org to production”
• “Make ‘staging’ my default Salesforce org”

39. Clear Default Org

Clear the default target org from the Salesforce CLI configuration. After clearing, all tools will require an explicit targetOrg parameter.

Example prompts:

• “Clear the default Salesforce org”
• “Remove the default target org setting”
• “Unset my default org”

40-47. Bulk API 2.0 Tools

Bulk API 2.0 tools run large DML jobs asynchronously through the existing org connection. Each tool starts a job, waits up to wait seconds (default 30, max 45), and returns the jobId, state, processed and failed counts, and up to 10 sample failures. If the job is still running, call bulk_job_status with the jobId. Input is one of inline records (max 2000 rows, 10 MB serialized), a csvPath to a UTF-8 CSV file on the server’s disk (max 150 MB), or csvContent, the raw CSV text with its header row (max 10 MB). Use records for small inline sets, csvPath for a file already on the server’s disk, and csvContent when the file cannot be read from the server’s machine, for example when it was uploaded into a sandboxed client such as Claude Cowork (the client passes the file’s text, and the server never sees the file’s path). Exactly one of the three is allowed. Delete tools take ids in place of records.

• bulk_insert_records: insert records. Do not include Id.
• bulk_update_records: update records by Id. Inline Id values are format-checked before the job is created; Id values in a CSV are not, and a malformed one fails only its own row. Updates above 500 rows ask the user to confirm when the client can prompt; a failed or declined prompt blocks the update. Without prompt support the update runs.
• bulk_upsert_records: insert or update on an external ID field (externalIdField, a field on the object itself). Upserts above 500 rows follow the same confirmation rule as updates.
• bulk_delete_records: soft delete by ids or a CSV with an Id column. If the client can show a confirmation prompt, the user is asked and declining blocks the delete. If it cannot (for example Claude Cowork, which has its own tool approval), pass confirm: "DELETE " and approve the call in the client; without the exact string the delete is refused.
• bulk_hard_delete_records: permanent delete. Requires confirm: "HARD DELETE " in every client, and also asks the user to confirm when the client can prompt. Needs the Bulk API Hard Delete permission.
• bulk_job_status: read-only check of a job.
• bulk_job_results: writes successful-results.csv, failed-results.csv and unprocessed-records.csv to ~/salesforce-bulk-results// (your home directory), or to outputDir if given. The result folder itself must not be a symbolic link, for the default folder as well as a custom one; symbolic links in parent folders are not checked. A custom outputDir must be an absolute path and must not already contain these files. The default folder is overwritten on re-run.
• bulk_job_abort: aborts a job that has not finished. Jobs are never deleted by these tools.

Set READ_ONLY=true to block all Bulk API writes, including bulk_job_abort. bulk_job_status and bulk_job_results still work, because bulk_job_results only writes local files. Upload and create failures return the jobId and abort the job when the upload did not complete.

Async pattern: start tools wait for up to wait seconds. If the job is still running, the response includes the jobId and state. Poll with bulk_job_status until the state is JobComplete, Failed or Aborted, then call bulk_job_results for full success, failure and unprocessed CSVs. Jobs are never deleted by these tools.

Path policy: csvPath must be absolute, end in .csv, point to an existing regular file (symlinks are followed, so the target is what counts), be at most 150 MB, and be UTF-8 with a header row and at least one data row (a header-only or blank-line-only file is refused). There is no folder restriction: any .csv the server process can read can be uploaded to the connected org, so an MCP client can send any local CSV it can name. outputDir must be absolute, must not be a symbolic link or a non-directory, and is created if missing; there is no folder restriction either, so result folders can be written anywhere the server process can write. Only the final folder is checked for symbolic links, not its parents. csvContent is not a path, so the path policy does not apply to it; it is checked only for size, header, required columns and line endings.

CSV rules (csvPath and csvContent): header names must not have leading or trailing spaces, because Bulk API reads them as written. Every line break must use the same ending as the header row (all LF or all CRLF), so a mixed file is refused before upload. Quotes count only at the start of a cell, so a stray quote inside a value is ordinary text.

Limits and gotchas:

• Inline records are capped at 2000 rows and 10 MB of serialized CSV. csvContent is capped at 10 MB of text (UTF-8 bytes, including the header row), and the text is sent in the tool call, so use csvPath for larger volumes (max 150 MB per file). Current org limits are available from the org_limits resource.
• Null values are written as #N/A, which clears the field on the Salesforce side. Keys missing from a record are left as empty cells, which do not change existing values on update.
• Nested objects are flattened to dotted relationship headers, for example Account.ExternalId__c. Records from SOQL results have their attributes metadata dropped.
• Updates must include Id on every row, and upserts must include the external ID field. Inserts and upserts should not include Id; the tools do not strip it, and Salesforce rejects or reports those rows.
• Hard delete needs the ‘Bulk API Hard Delete’ system permission on the running user (usually granted through a profile or permission set, and by default only to System Administrators). Without it, the tool returns a permission error.
• Records are processed in batches and rows are not rolled back. A job can report partial success, so always check failed-results.csv before retrying.

Available Resources

The server exposes MCP Resources that clients can browse and include in conversations for contextual data about your Salesforce orgs.

Resources support autocomplete for org aliases and object names. Template resources (2-5) respect the ALLOWED_ORGS permission setting.

Available Prompts

The server provides MCP Prompts — templated workflows that appear as slash commands in clients like Claude Desktop. They fetch live org data and guide the AI through common Salesforce tasks.

All prompts respect the ALLOWED_ORGS permission setting and use the default org when targetOrg is not provided.

Practical Examples

Example 1: Data Analysis

User: "I need to analyze our customer data. First, show me what custom objects we have in the production org."

AI: [Lists all custom objects]

User: "Great! Now query all Customer__c records created this year and export them to CSV."

AI: [Executes query and creates CSV file]

Example 2: Debugging

User: "I'm having issues with a trigger. Can you execute this Apex to test it:
List accs = [SELECT Id, Name FROM Account LIMIT 5];
for(Account a : accs) {
    System.debug('Account: ' + a.Name);
}"

AI: [Executes the code and shows debug logs]

Example 3: Schema Documentation

User: "I need to document our data model. Can you describe the Order__c object including all its fields and relationships?"

AI: [Provides detailed object metadata]

Logging

The server emits structured MCP log messages (notifications/message) with typed severity levels and named loggers. Clients that support the MCP logging capability will receive these messages automatically.

Logger names: salesforce, cli, permissions

Log levels used:

• debug — CLI command execution details
• info — Server startup and general status
• warning — Permission denials
• error — Command failures and connection errors
• critical — Authentication/auth-info failures

Clients can set a minimum log level via the logging/setLevel request to filter out lower-severity messages.

Progress Reporting

Long-running tools report real-time progress via MCP progress notifications (notifications/progress). Clients that include a progressToken in _meta when calling a tool will receive progress updates with step messages.

Tools with progress reporting:

• deploy_start — Resolving target org → Validating permissions → Deploying metadata
• run_apex_tests — Resolving target org → Validating permissions → Running Apex tests
• scanner_run — Validating permissions → Running scan
• scanner_run_dfa — Validating permissions → Running data flow analysis
• run_code_analyzer — Validating permissions → Running code analysis
• query_records_to_file — Resolving target org → Validating permissions → Exporting records to file

Progress is reported as fire-and-forget notifications and will never interrupt tool execution. Clients that don’t provide a progress token will not receive any notifications.

Elicitation (User Confirmation)

Destructive operations request user confirmation via MCP elicitation before proceeding. When a client supports elicitation, the server will prompt the user with a confirmation dialog before executing the operation.

Tools that request confirmation:

• delete_record — Confirms before permanently deleting a Salesforce record
• package_uninstall — Confirms before uninstalling a package from the org
• logout — Confirms before logging out of a specific org or all orgs
• deploy_start — Confirms before deploying metadata (skipped for dry-run/validation-only deployments)

Elicitation degrades gracefully: if the client does not support elicitation, or the server has not been initialized, operations proceed without confirmation. This ensures backward compatibility with all MCP clients.

Completions (Argument Auto-Complete)

Prompt arguments and resource URI variables support auto-completion via the MCP Completions API. When a client sends a completion/complete request, the server returns matching suggestions.

Prompt argument completions:

• targetOrg — All 5 prompts auto-complete with connected org aliases filtered by ALLOWED_ORGS
• objectName (soql_builder) — Auto-completes with SObject API names from the resolved target org

Resource URI completions:

• {alias} — All template resources auto-complete with connected org aliases
• {name} (org_object_schema) — Auto-completes with SObject names from the resolved org

Completions are powered by the SDK’s completable() wrapper and require no additional client configuration.

Server Title & Icon

The server provides a human-readable title (“Salesforce MCP Server”) and an embedded icon in its metadata. Clients that support the MCP Implementation metadata (SDK 1.25+) will display the server name and icon in their UI. Tool-level icons are not currently supported by the MCP SDK.

Structured Tool Output

The following tools support MCP structured output (outputSchema + structuredContent) for programmatic result parsing:

• query_records — returns { targetOrg, records }
• sobject_list — returns { targetOrg, sobjects }
• sobject_describe — returns { targetOrg, name, label, fields, childRelationships, recordTypeInfos, ... }
• list_connected_salesforce_orgs — returns { devHubOrgs, production, sandboxes, scratchOrgs, totalOrgs, permissionMessage?, note } (usernames, org IDs and instance URLs always masked)
• get_apex_test_results — returns { targetOrg, summary, tests, codecoverage }

Clients that support the MCP outputSchema capability will receive validated structured data in addition to the text content. All tool schemas are advertised with the JSON Schema 2020-12 dialect so that clients validating outputSchema with a 2020-12-only validator accept them.

Tips for Best Results

1. Specify the Target Org: Always mention which org you want to work with (e.g., “in my dev org”, “using production”)

2. Be Specific with Queries: Provide field names and conditions for SOQL queries

   • Good: “Query Account records with Type = ‘Customer’ and show Id, Name, and CreatedDate”
   • Less specific: “Get some Accounts”

3. Object Names: You can use either user-friendly names or API names - the AI assistant will use the describe tools to find the correct API names

   • Both work: “Query Custom Object records” or “Query Custom_Object__c records”
   • The assistant will automatically resolve field names too

4. Apex Code Formatting: When providing Apex code, you can use code blocks or inline code

5. File Exports: Specify the format (CSV or JSON) when exporting query results

Troubleshooting

“No orgs found”: Make sure you have authenticated orgs using sf org login

“Object not found”: Verify the object exists and you’re using the correct API name

“Query error”: Check your SOQL syntax and field names

“Apex execution failed”: Review the debug logs for specific error messages

“Tool … has an invalid outputSchema: JSON Schema declares an unsupported dialect”: Update to the latest server version — tool schemas are now published as JSON Schema 2020-12 instead of draft-07

Security Considerations

• The server executes commands with the permissions of the authenticated Salesforce user
• While client browser mode is enabled, open and open_record return URLs that contain a one-time Salesforce login token — whoever opens one first is logged in as you, so keep them out of shared logs and tickets
• Be cautious when executing DML operations in production orgs
• Review Apex code before execution, especially in production environments
• Consider using sandbox orgs for testing and development

Building MCP Bundle (MCPB) Locally

If you want to build the MCP Bundle file yourself:

1. Clone the repository and navigate to the salesforce-mcp-server directory
2. Install dependencies: npm install
3. Build the MCPB file: npm run build:mcpb
4. The .mcpb file will be created in the dist/ directory
5. Share this file with others for easy one-click installation

For more details about MCP Bundles, see MCPB.md