How to Convert a Lead Using Salesforce MCP

Defining Invocable Variables for the Lead Conversion Method

There are three parameters we need: the ID of the Lead we want to convert, a flag to store whether we want to create a new Opportunity or not, and the name of the new Opportunity if we want a new one. All of them will have to be annotated with @InvocableVariable.

global class ConvertLeadRequest {

	@InvocableVariable(Label = 'Lead Id' Required = true)
	public String leadId;

	@InvocableVariable(Label = 'Create Opportunity' Required = true)
	public Boolean createOpp;

	@InvocableVariable(Label = 'Opportunity Name' Required = false)
	public String oppName;

}

Implementing the Invocable Apex Logic

Our method, which will have to work with MCPs, needs to be annotated with @InvocableMethod and take List as its parameter. First, it will fetch the Leads with the given IDs, which usually consists of only one Lead ID. It will then check their respective Company fields and fetch the Accounts based on those Company values. If it finds a match, it will need to attach the newly created Contact to the existing Account that matches. Otherwise, it will create a new Account. It will also take our parameters createOpp and oppName into consideration during conversion to a new Opportunity. All things considered, our method will look like this:

@InvocableMethod(
        Label = 'Convert Lead'
        Description = 'Converts a Lead'
        Callout = false
)
global static void convertLead(List<ConvertLeadRequest> requests) {
    System.debug('ConvertLeadInvocable.convertLead start');
    List<Boolean> isSuccessful = new List<Boolean>();

    Set<Id> leadSet = new Set<Id>();
    for (ConvertLeadRequest clr : requests) {
        leadSet.add(clr.leadId);
    }

    Map<Id, Lead> leadMap = new Map<Id, Lead>([
            SELECT Id, Name, Company
            FROM Lead
            WHERE Id IN :leadSet
    ]);

    Set<String> accountSet = new Set<String>();
    for (Lead ld : leadMap.values()) {
        accountSet.add(ld.Company);
    }

    Map<String, Account> accountMap = new Map<String, Account>([
            SELECT Id, Name
            FROM Account
            WHERE Name IN :accountSet
    ]);

    System.debug('accountMap: ' + accountMap);

    List<Database.LeadConvert> leadContexts = new List<Database.LeadConvert>();
    for (ConvertLeadRequest clr : requests) {
        Lead leadTemp = leadMap.get(clr.leadId);

        Database.LeadConvert lc = new Database.LeadConvert();
        lc.setLeadId(clr.leadId);
        lc.setConvertedStatus(LEAD_CONVERSION_STATUS);
        lc.setDoNotCreateOpportunity(!clr.createOpp);
        lc.setOpportunityName(clr.oppName);
        lc.setBypassAccountDedupeCheck(false);
        lc.setBypassContactDedupeCheck(false);

        Account companyTemp = accountMap.get(leadTemp.Company);
        if (companyTemp != null && companyTemp.Id != null) {
            System.debug('Found a company for ' + leadTemp.Name + ': ' + companyTemp.Id);
            lc.setAccountId(companyTemp.Id);
        }

        leadContexts.add(lc);
    }

    System.debug('leadContexts: ' + leadContexts);
    List<Database.LeadConvertResult> results = Database.convertLead(leadContexts, true);
    // allOrNothing is set as true so that the agent will return an error in case of failure

    for (Database.LeadConvertResult res : results) {
        if (!res.isSuccess()) {
            System.debug('Conversion failed: ' + String.valueOf(res.getErrors()));
        }
        isSuccessful.add(res.isSuccess());
    }

    System.debug('ConvertLeadInvocable.convertLead end');
}

You may have noticed the variable named LEAD_CONVERSION_STATUS. This is intentionally left there — you can replace it with the customized Lead Converted status on your org or assign it as a static variable in class context, above the method.

global static final String LEAD_CONVERSION_STATUS = 'Closed - Converted';

It’s also worth noting that Lead conversion will fail if the Lead is owned by a queue. Therefore, if your org can have such a case, it is worth running the setOwnerId(Id) method when values are being set for the Database.LeadConvert object.

This will take care of the Apex side of our mechanism. However, our work on Salesforce is not done; our MCP is still not capable of using the method we just built, we need to introduce it manually.

(In a production environment, our Apex class would have to be accompanied by a test class, which is out of our scope for this article)

Adding Your Invocable Apex Action to the Salesforce MCP Server

Go back to Setup → MCP Servers and navigate to the MCP server mentioned. Click the Add Server Assets button and pick the “Add Tools” option. You should be able to see the method there. Click the Add Tool button and then click Save.

Since our conversion method works with Lead IDs, we also need our MCP to run SOQL queries to fetch those IDs when the name of a Lead is given. Hence, we should also add the SOQL tool. Click the Add Server Assets button and pick the “Add from Server” option. Go to the SObject All MCP server and pick the Query Records (SOQL) tool. Click Done.

Finally, activate your MCP through the Activate button on the top right.

We have now successfully introduced our method to the MCP and are now halfway there towards our three-way party.

How to Connect Claude Desktop to Salesforce via MCP

Now, let us move to the other side of the equation: the AI agent. To connect our Salesforce org with our agent, we need to introduce our MCP to the model. We will use Salesforce’s External Client App functionality for this integration.

Before doing so, we need to configure our OAuth settings. Navigate to Setup → OAuth and OpenID Connect Settings and enable Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows. This strengthens our org’s OAuth configuration and allows Claude to connect successfully.

Next, open your Claude client and navigate to Settings → Connectors. Click Add in the top-right corner to create a custom connector. As of September 2026, Claude does not offer an out-of-the-box Salesforce connector. The setup screen will ask for a name and your MCP server URL, which you can find under your MCP details. Choose a name that clearly distinguishes this connector from your others, then paste your MCP URL into the appropriate field.

Configuring Salesforce OAuth for Claude

If the connector setup also asks you for a Client ID and Client Secret, or if you are receiving an error with the reference code “ofid_e99841b04f01022e” after creating your connector, go to Setup → External Client App Manager. Create a new External Client App and give it a name of your choosing. Make sure that:

• the Enable OAuth checkbox is checked
• selected OAuth scopes include Access Salesforce hosted MCP servers (mcp_api) and Perform requests at any time (refresh_token, offline_access)
• Require secret for Web Server Flow and Require secret for Refresh Token Flow are unchecked under the Security subsection
• Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows is checked
• Issue JSON Web Token (JWT)-based access tokens for named users is checked

Go to the Tools tab and then the OAuth Settings section of the External Client App. Click the Consumer Key and Secret button. Verify yourself when prompted, and copy the Consumer Key and Secret. Paste them to the input boxes on the Claude client.

If you are not prompted for a Client ID and Client Secret, you can skip to the part ahead.

Completing Claude Authentication and MCP Connection

You will then be asked to self-authenticate, both on Claude and on Salesforce. Do both, and if everything goes smoothly, your MCP will be connected.

Now let’s put our code to test by converting a Lead of our choosing. I will convert Mike Braund from the standard Salesforce record data that is present on all Developer Edition orgs (hence no distinguishing PII is given below).

Testing the Lead Conversion Prompt in Claude

We will try to convert our Lead with a simple prompt: “Convert the lead named "Mike Braund" on my Salesforce org. Make sure that the opportunity name is "Mike Braund 2026"“. This way we will also test if Claude can fetch the parameters it has been given and assign them accordingly.

To achieve its task, Claude will occasionally ask for permissions. Make sure to give them to it by pressing any option that starts with “Allow”. The screenshot below notifies us that Claude is ready to run our Apex method.

Once all necessary permissions are given, and all tasks are done, Claude will notify you that the task is completed successfully. It will even run a second SOQL query to ensure that the IsConverted flag of the Lead is checked.

Claude isn’t lying. If we navigate to the page of Mike Braund on our org, we will see that the Lead is converted successfully; there is now a Contact in its place which is linked to a new Account and an Opportunity.

Therefore, our experiment is successful; we can now do one of our most basic tasks through our AI agents instead of clicking, effectively saving time which can then be spent on actually getting the Leads that are to be converted.

Start Automating Your Salesforce Workflows with AI Agents Today

AI agents are becoming smarter and more capable with every passing day. Salesforce users and developers should hand repetitive, time-consuming tasks over to these AI tools. Developers must ensure these tools support people rather than replace their jobs. The goal is to help people work more efficiently and with less effort. A good approach is to start small and build confidence with familiar, repetitive Salesforce tasks.

Explore related content:

AIforce: Salesforce’s New AI Interface Layer for Slack, Claude, and Lightning

Agentforce Agent Flow Action Best Practices

Accounts and Contacts in Salesforce: The Foundation Every Admin Needs to Get Right