MCP Setup

The Model Context Protocol (MCP) creates a direct bridge between Cursor's built-in AI agent and your Salesforce orgs. Once set up, you can chat with Cursor's AI using natural language, and it will execute Salesforce commands directly-querying data, deploying components, and managing your orgs without you needing to type CLI commands.

What You Need First

Before starting, make sure you have:

1. Cursor installed on your machine
2. Salesforce CLI installed (covered in macOS Environment Setup)
3. At least one authenticated org (you can check by running sf org list in your terminal)

Simple Setup (5 Minutes)

---
description: Always prefer the Salesforce MCP for org operations
alwaysApply: true
---

When the user asks about orgs, metadata, queries, deploys, or users:

- Use the Salesforce MCP first. Only fall back to `sf` CLI text if the
  MCP cannot handle the request or is unavailable.
- Before deploying, list what would change and confirm the target org
  alias in chat.

list all my connected orgs

show me my default org

run this query: SELECT Id, Name FROM Account LIMIT 5

Manual Configuration (Optional)

If you prefer to manually configure the MCP server or need to customize the setup, follow these steps:

{
  "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" ]
    }
  }
}

Using the MCP

Open Cursor's AI Chat

• Chat Panel: Click the chat icon in the left sidebar
• Keyboard: Cmd/L (Mac) or Ctrl/L (Windows)
• Inline: Cmd/K (Mac) or Ctrl/K (Windows)

Set up automatic MCP usage

Add a project rule at .cursor/rules/salesforce-mcp.mdc (see Rules & AGENTS.md) so Cursor uses the MCP for Salesforce operations without being asked.

Real-World Examples

Here are practical ways to use the Salesforce MCP in your daily development workflow. With the project rule in place, you can use simple, natural language:

Query Data

show me all contacts for Acme Corporation

find opportunities that closed this month with amount over $50k

get the picklist values for the Stage field on Opportunity

Deploy Code

deploy my lwc component to the default org

deploy everything in the force-app directory

Check Org Info

list all my connected orgs

show me all custom objects in my org

Create Test Data

create 10 test accounts with realistic company names

add 5 opportunities to the account I just created

Advanced Configuration

Using a Specific Org

By default, the MCP connects to your DEFAULT_TARGET_ORG. To use a specific org instead, replace DEFAULT_TARGET_ORG with your org's alias:

{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp@latest", 
               "--orgs", "my-dev-sandbox",
               "--toolsets", "orgs,metadata,data,users",
               "--tools", "run_apex_test",
               "--allow-non-ga-tools" ]
    }
  }
}

Multiple Org Setup

To work with multiple orgs simultaneously, configure separate MCP servers with different names:

{
  "mcpServers": {
    "Salesforce Dev": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp@latest", 
               "--orgs", "dev-sandbox",
               "--toolsets", "orgs,metadata,data,users",
               "--tools", "run_apex_test",
               "--allow-non-ga-tools" ]
    },
    "Salesforce UAT": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp@latest", 
               "--orgs", "uat-sandbox",
               "--toolsets", "orgs,metadata,data,users",
               "--tools", "run_apex_test",
               "--allow-non-ga-tools" ]
    }
  }
}

Then specify which server to use in your chat: "Use the Salesforce Dev MCP to..." or "Use the Salesforce UAT MCP to..."

Customizing Toolsets

The --toolsets parameter controls which operations are available. You can customize this to limit or expand functionality:

{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp@latest", 
               "--orgs", "DEFAULT_TARGET_ORG",
               "--toolsets", "orgs,data",
               "--allow-non-ga-tools" ]
    }
  }
}

Available toolsets:

• orgs - Org management (list, open, create, delete)
• metadata - Deploy and retrieve metadata
• data - Query and manage data
• users - User and permission management

Tips for Better Results

Automatic MCP usage via a project rule

Instead of typing "Use the Salesforce MCP" into every chat, add a project rule at .cursor/rules/salesforce-mcp.mdc:

---
description: Always prefer the Salesforce MCP for org operations
alwaysApply: true
---

When the user asks about orgs, metadata, queries, deploys, or users:

- Use the Salesforce MCP first. Only fall back to `sf` CLI text if the
  MCP cannot handle the request or is unavailable.
- Before deploying, list what would change and confirm the target org
  alias in chat.
- For multi-org setups, name the MCP explicitly rather than guessing.

For the full breakdown of project rules, global rules, and AGENTS.md, see Rules & AGENTS.md.

Combine with File References

Reference files in your project:

check if @myComponent.js is deployed to my org

Ask Follow-ups

Cursor remembers conversation context:

explain why that SOQL query returned no results

Handle Complex Workflows

Chain multiple operations in one request:

show me all contacts at Acme Corp, then create a follow-up task for each one

Troubleshooting

MCP Server Not Working

No Orgs Found

Slow Responses

If queries take too long:

• Limit results: "show me 10 records" instead of "show me all records"
• Add filters to narrow data
• Break complex requests into smaller queries

Staying Updated

To manually update:

npm install -g @salesforce/mcp@latest

Check official releases for new features.

What's Next?

Now that Cursor is connected to your Salesforce org via MCP, you can:

• Create your first Salesforce project and build your first Lightning Web Component
• Explore the Prompt Library for powerful ways to use Cursor with Salesforce
• Continue to Agentforce DX to learn about building agents from the command line