Configure Salesforce MCP Server for Claude Code & MCP Clients

1 What is Model Context Protocol (MCP)?

According to the official Salesforce Developers blog, MCP acts as a "universal translator between AI agents and your business data" - similar to how USB standardized device connections. This standardization allows any MCP-compatible AI client to work with any MCP server without custom integrations.

Why MCP Matters for Salesforce Development

Before MCP, integrating AI assistants with Salesforce required custom code, API wrappers, and significant development effort. With MCP, you can:

• Query Salesforce data directly from your IDE using natural language
• Deploy and retrieve metadata without switching to command line
• Run Apex tests and get results analyzed by AI
• Manage users and permissions through conversational commands
• Get LWC development assistance with context-aware suggestions

Example: "Get me Opportunities from last quarter"

2 Salesforce MCP Server Options

Salesforce provides two official approaches to MCP connectivity, each designed for different use cases. Understanding these options helps you choose the right setup for your workflow.

3 Salesforce DX MCP Server Setup

The Salesforce DX MCP Server is the recommended approach for developers already using Salesforce CLI. It provides the most comprehensive set of tools and requires minimal configuration.

Prerequisites

1. Install Salesforce CLI

Download from Salesforce CLI page or use npm:

npm install -g @salesforce/cli

2. Authorize Your Org

Authenticate your Salesforce org (replace YOUR_ORG_ALIAS with your preferred alias):

sf org login web -a YOUR_ORG_ALIAS

3. Verify Node.js Version

MCP requires Node.js 18 or higher:

node --version

Configuration for Claude Code

Create or edit your .mcp.json file in your project root (for project-scope) or ~/.claude.json (for user-scope):

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

Configuration Flags Explained

Verify Connection

After configuring, restart Claude Code and use the /mcp command to check server status. You should see "Salesforce DX" listed with available tools.

4 Available Toolsets & Tools

The Salesforce DX MCP Server organizes its 60+ tools into logical toolsets. According to the @salesforce/mcp npm package, you can selectively enable toolsets to reduce context window consumption and improve performance.

Example: Focused Development Setup

For a typical LWC development workflow, use this focused configuration:

{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp",
        "--orgs", "my-dev-org",
        "--toolsets", "orgs,metadata,lwc-experts,testing"
      ]
    }
  }
}

5 Salesforce Hosted MCP Servers (Beta)

According to the Salesforce Developers announcement, Hosted MCP Servers run on Salesforce infrastructure and expose specific Salesforce APIs as MCP tools - all without writing code. These servers use OAuth authentication and require the mcp-remote package to connect from stdio-based clients like Claude Code.

Available Endpoints

Setup Requirements

Before connecting to Hosted MCP Servers, complete these steps in your Salesforce org:

1. Enable MCP Service (Beta)

Setup > User Interface > User Interface > Enable MCP Service (Beta)

2. Create External Client App

Setup > Apps > App Manager > New External Client App

Configure the External Client App with OAuth settings for MCP access:

3. Configure Security Settings

Set up the security policies for your External Client App:

4. Save Client Credentials

After saving, click "Manage Consumer Details" to copy your Consumer Key (client_id) and Consumer Secret (client_secret) for MCP configuration.

6 OAuth Configuration & Scopes

OAuth authentication is required for Salesforce Hosted MCP Servers. According to the Salesforce OAuth documentation, you need to configure specific scopes to enable MCP functionality.

Required OAuth Scopes

OAuth Authorization URL Example

When using mcp-remote with OAuth, the authorization flow uses URLs like this:

https://login.salesforce.com/services/oauth2/authorize?
  response_type=code
  &client_id=YOUR_CONSUMER_KEY
  &code_challenge=GENERATED_CODE_CHALLENGE
  &code_challenge_method=S256
  &redirect_uri=http://localhost:8080/oauth/callback
  &state=UNIQUE_STATE_STRING
  &scope=api sfap_api refresh_token einstein_gpt_api

External Client App Configuration

For Hosted MCP Servers, create an External Client App as described in Section 5. The key OAuth settings are:

Callback URL for Claude Code:

http://localhost:8080/oauth/callback

Required OAuth Scopes:

• api - Manage user data via APIs
• refresh_token - Perform requests at any time (offline_access)
• sfap_api - Access the Salesforce API Platform
• einstein_gpt_api - (Optional) Access Einstein GPT services

After saving, click "Manage Consumer Details" to copy your Consumer Key (client_id) and Consumer Secret (client_secret).

7 mcp-remote Configuration

The mcp-remote package bridges stdio-only MCP clients (like Claude Code) to remote MCP servers with OAuth support. It handles the authentication flow and protocol translation automatically.

Basic Configuration

Add this to your .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.salesforce.com/platform/mcp/v1-beta.2/sobject-all",
        "8080",
        "--static-oauth-client-info",
        "{"client_id":"YOUR_CONSUMER_KEY","client_secret":"YOUR_CONSUMER_SECRET"}"
      ]
    }
  }
}

mcp-remote Flags Reference

Using Environment Variables

For better security, use environment variables instead of inline credentials:

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.salesforce.com/platform/mcp/v1-beta.2/sobject-all",
        "8080",
        "--static-oauth-client-info",
        "{"client_id":"${SF_CLIENT_ID}","client_secret":"${SF_CLIENT_SECRET}"}"
      ],
      "env": {
        "SF_CLIENT_ID": "YOUR_CONSUMER_KEY",
        "SF_CLIENT_SECRET": "YOUR_CONSUMER_SECRET"
      }
    }
  }
}

Using File-Based Credentials

You can also reference a JSON file containing credentials:

# Create credentials file
echo '{"client_id":"YOUR_KEY","client_secret":"YOUR_SECRET"}' > ~/.salesforce-oauth.json

# Reference in configuration
"--static-oauth-client-info", "@/Users/yourname/.salesforce-oauth.json"

8 Troubleshooting Common Issues

"No code verifier saved for session"

This error occurs when OAuth tokens expire or when switching between MCP server endpoints.

# Clear cached credentials
rm -rf ~/.mcp-auth/

# Restart Claude Code and re-authenticate

"MCP server not connected"

Check the following:

• Verify Node.js version is 18+ with node --version
• Check JSON syntax in your .mcp.json file
• Ensure Salesforce CLI is installed and orgs are authorized
• Run /mcp in Claude Code to see detailed error messages

"401 Unauthorized" with Hosted MCP

OAuth configuration issues. Verify:

• Consumer Key and Secret are correct
• Connected App has required OAuth scopes enabled
• Callback URL matches exactly: http://localhost:8080/oauth/callback
• MCP service is enabled in your Salesforce org

DX MCP Server Shows No Tools

The --orgs flag is required. Ensure you've specified at least one authorized org:

# List authorized orgs
sf org list

# Use a valid org alias in your configuration
"--orgs", "your-org-alias"

Enable Debug Logging

For DX MCP Server:

{
  "args": ["--debug", "--orgs", "my-org", ...]
}

For mcp-remote:

# Add --debug flag
"args": ["mcp-remote", "URL", "--debug"]

# Check logs at
cat ~/.mcp-auth/*_debug.log

9 Frequently Asked Questions

Related Reading

Continue your Salesforce and AI development journey with these related guides:

• Claude Code: The Complete Guide - Master Anthropic's AI-powered CLI tool from basic setup to advanced MCP servers and IDE integrations
• Agentforce Vibes: The Complete Developer Guide - Learn enterprise vibe coding with Salesforce Agentforce platform
• Salesforce Agentforce Out-of-Box Agents: Complete Analysis - Comprehensive overview of pre-built AI agents, capabilities, and pricing
• Moltbot Complete Guide (Formerly ClawdBot) - Open-source AI assistant for developers and teams

10 Abbreviations & Glossary