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.

Beyond the Platform: Other Salesforce MCP Servers

Alongside DX MCP and Platform Hosted MCP, the broader Salesforce ecosystem now ships several specialized MCP servers. They are out of scope for this guide but worth knowing about:

• Heroku MCP Server (GA) - manage Heroku apps, dynos, and add-ons via natural language.
• MuleSoft MCP Server (GA) - design, deploy, and operate MuleSoft projects from an AI client.
• Mobile MCP Server (Developer Preview, January 2026) - generate native mobile app code with Mobile SDK.
• Agentforce MCP Client - Agentforce can itself act as an MCP client and consume external MCP servers, with a registry and policy enforcement layer.

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 (Generally Available)

Salesforce Hosted MCP Servers moved from beta to General Availability in April 2026, announced on the Salesforce Developers blog (with the GA milestone covered in the April 2026 Developer Edition update). They run on Salesforce infrastructure and expose Salesforce APIs as MCP tools without writing code. These servers authenticate via OAuth 2.0 + PKCE through an External Client App, and stdio-based clients like Claude Code connect through the mcp-remote package.

Available Endpoints (GA Catalog)

Sandbox / scratch orgs: swap /v1/platform/ for /v1/sandbox/. For example: https://api.salesforce.com/platform/mcp/v1/sandbox/sobject-all.

Setup Requirements

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

1. Enable MCP Service

Setup > User Interface > User Interface > Enable MCP Service

2. Create External Client App

Setup > Apps > App Manager > New External Client App

Configure the External Client App with OAuth settings for MCP access. External Client Apps are required for Hosted MCP; classic Connected Apps are not supported for this flow.

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. With the GA release, Salesforce surfaces two named scopes in the External Client App UI specifically for MCP - see the Create an External Client App guide.

Required OAuth Scopes (GA)

OAuth Authorization URL Example

The Authorization Code + PKCE flow used by Hosted MCP produces 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=<CLIENT_CALLBACK_URL>
  &state=UNIQUE_STATE_STRING
  &scope=mcp+refresh_token

Callback URLs by MCP Client

Different MCP clients expect different callback URLs. Add every client URL you plan to use to your External Client App's "Callback URL" field (one per line). The Connect MCP Clients overview page links out to per-client guides (Claude, Cursor, Postman, ChatGPT) where the exact callback URLs are documented; the table below summarizes the values used at the time of writing.

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(s): add the URLs from the table above for every client you'll use.
• Scopes: "Access MCP servers" + "Perform requests at any time".
• PKCE: enabled (required by Hosted MCP).
• Permitted Users: "Admin approved users" or "All users may self-authorize" depending on your security model.

After saving, click "Manage Consumer Details" to copy your Consumer Key (client_id) and Consumer Secret (client_secret). Salesforce notes propagation can take up to 30 minutes after first save.

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.

Verified Configuration (April 2026)

Add this to your .mcp.json or ~/.claude.json. This is the configuration the author uses against the GA Hosted MCP Server after the previous beta URL stopped responding:

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

mcp-remote Flags Reference

Using Environment Variables

For better security, keep credentials out of the JSON and inject them through environment variables:

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.salesforce.com/platform/mcp/v1/platform/sobject-all",
        "8080",
        "--static-oauth-client-info",
        "{"client_id":"${SF_CLIENT_ID}","client_secret":"${SF_CLIENT_SECRET}"}"
      ],
      "env": {
        "SF_CLIENT_ID": "YOUR_CLIENT_ID",
        "SF_CLIENT_SECRET": "YOUR_CLIENT_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

"404" or No Response from Hosted MCP URL

Almost always a stale URL. Confirm:

• You are not using https://api.salesforce.com/platform/mcp/v1-beta.2/... - that beta URL was retired at GA.
• Production URL pattern: https://api.salesforce.com/platform/mcp/v1/platform/<server>
• Sandbox/scratch URL pattern: https://api.salesforce.com/platform/mcp/v1/sandbox/<server>
• The <server> name matches an entry in the endpoint catalog (for example, sobject-all, not sobject_all).

"401 Unauthorized" with Hosted MCP

OAuth configuration issues. Verify:

• Consumer Key and Secret are correct
• External Client App has the OAuth scopes "Access MCP servers" and "Perform requests at any time" enabled
• Callback URL on the External Client App matches your client (e.g., http://localhost:8080/oauth/callback for mcp-remote, or https://claude.ai/api/mcp/auth_callback for Claude direct)
• PKCE is enabled on the External Client App
• MCP service is enabled in Setup → User Interface
• Wait up to 30 minutes after first save - External Client App settings can take that long to propagate.

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