Skip to main content
Salesforce The Salesforce app provides read/write access to a Salesforce org through the Salesforce REST API v62.0. It can be consumed two ways: as a remote MCP server that Agent Factory agents call as tools, or as a Builder app whose instructions you call directly from DSUL. The MCP surface groups every operation into thematic dispatcher tools (records, query, bulkIngest, tooling, …), each driven by an action argument, and runs in the tenant app-instance context (it resolves the installing workspace’s own Salesforce credentials and gates each agent against a per-workspace allowlist). Authentication is resolved server-side and supports several modes:
  • OAuth2 JWT Bearer (jwt, default) — service-to-service auth through a Connected App and a service-account user. No interactive sign-in.
  • OAuth2 client credentials (clientCredentials) — the Connected App’s client_credentials grant, run as the configured Connected App user.
  • Per-user OAuth2 (oauth) — each end user signs in with their own Salesforce account (authorization-code + PKCE); tokens are stored per user and auto-refreshed.
  • Direct access token (accessToken) — a caller-managed Salesforce access token + instance URL, used as-is with no exchange.

CRM Records

Create, read, update, delete and upsert sObjects (Accounts, Contacts, Leads, Opportunities, custom objects) and run SOQL / SOSL searches across them

Bulk & Composite

Bulk API 2.0 ingest/query jobs and Composite endpoints for high-volume, multi-record and atomic operations

Reports & Process

Reports, dashboards, approval processes, quick actions, Tooling API (Apex + metadata) and Metadata package deploys

Who is this for?

This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.

Agent builder

You build agents in Agent Factory and want them to read and act on Salesforce. → Agent builder tab.

Platform admin

You run the platform and want to publish Salesforce as a reusable capability. → Platform admin setup accordion below.

Workspace builder

You write Builder automations (DSUL) that call Salesforce operations directly. → Workspace builder tab.

Prerequisites (Salesforce side)

  • A Salesforce org with administrator access (Production, Developer Edition or Sandbox).
  • A Connected App created in Setup > App Manager > New Connected App, with OAuth Settings enabled. Its Consumer Key and Consumer Secret back the OAuth / JWT / client-credentials modes.
  • The OAuth scopes api refresh_token offline_access selected on the Connected App.
  • The Login Host matching the org type: https://login.salesforce.com for production / Developer Edition, https://test.salesforce.com for sandbox, or a custom My Domain host like https://<mydomain>.my.salesforce.com.
  • For JWT Bearer (default mode): enable Use digital signatures on the Connected App, upload the matching public certificate, pre-authorize the runtime user, and keep the matching RSA private key (PEM) plus the service-account username.
  • For per-user OAuth: the Connected App’s Callback URL must contain the connector’s auto-computed OAuth Redirect URI (shown in the configuration app after install).
Goal: Salesforce is a per-workspace connector — each workspace configures its own Connected App credentials and auth mode (see the Workspace builder tab), so there is no platform-wide credential to provision. The only optional platform task is to publish Salesforce as a reusable capability so agent builders across the org can enable it from the catalog instead of pasting a raw MCP endpoint.
There is no shared Salesforce credential and no central OAuth client for this connector. The Connected App credentials, the per-user OAuth tokens and the authorized-agents allowlist always live in the consuming workspace. A capability you publish here points at a specific workspace’s MCP endpoint; that workspace still owns the credentials and the allowlist.

1. Configure the connector

There is nothing to configure at the platform level. Each consuming workspace installs the Salesforce app, opens its Configuration app and provides its own Connected App credentials + auth mode (see the Workspace builder tab). The credentials are scoped to that workspace and never shared org-wide.

2. Declare the capability in AI Governance (optional)

You have two ways to make Salesforce discoverable as a capability. Both point at a workspace’s MCP endpoint and use the same Scope — pick whichever fits your governance model.
1

Easy path — one-click 'Add to catalog' from the config app

Open the connector’s Configuration app in the workspace that owns the credentials. As an org owner or admin, you’ll see an Add to catalog button (under Capabilities catalog). Clicking it publishes Salesforce to your organization’s Capabilities catalog as an mcp entry — pre-wired with the workspace’s MCP endpoint, the Scope context_id,agent_id,user_id, and (in oauth mode) the per-user connect / status / disconnect URLs. Once published it is org-wide: every builder in the org can attach it to an agent from the catalog. The button is only shown to org owners/admins, and it updates the existing entry if one already points at that endpoint.
2

Manual path — declare it yourself in AI Governance

Alternatively, open AI Governance > Capabilities, create (or edit) a Salesforce capability, set its MCP server URL to the connector’s MCP Endpoint, and set its Scope to:
context_id,agent_id,user_id
The agent_id in the scope is what lets the connector identify and authorize the calling agent.
3

Make it available to agent builders

Either path makes the capability appear in the capability picker for agent builders in your organization. Access to the catalog follows your organization’s existing roles; there is no per-capability role grant. Which agents may actually call this tenant-context connector is gated separately by the per-workspace allowlist (see below).
Declaring or publishing the capability makes the connector available; it does not by itself authorize a specific agent. This connector follows the tenant-context model — the catalog entry points at a workspace that still owns the credentials and the authorized-agents allowlist. An agent attaching the published capability still has to be allowlisted in that workspace’s config app (or the workspace must enable Allow all agents). There is no OAuth auth-config JSON to attach in Governance: connect / status / disconnect are handled by the connector’s own webhooks, wired automatically.

Agent builder

Goal: let an agent you build in Agent Factory read and act on Salesforce through MCP tools.
Before an agent can call the connector, a Workspace builder must have installed and configured the Salesforce app in a workspace (see the Workspace builder tab). Optionally, a Platform admin may have published a Salesforce capability (see the Platform admin setup accordion above).
This connector runs in the tenant app-instance context: your agent is authorized two ways at once — it is identified by the agent_id that Agent Factory injects through the capability Scope, and that agent must appear in the connector’s authorized-agents allowlist (managed in the configuration app). The Salesforce token itself is resolved server-side from the configured auth mode — never exposed to the agent.There are two ways to wire Salesforce into your agent.

Option A — Attach the published capability from the catalog

If a Platform admin used the config app’s Add to catalog button (or declared the capability manually), Salesforce appears in your agent’s capability picker pre-wired: the MCP endpoint and the Scope context_id,agent_id,user_id are already filled in. Just pick it and enable it.
The catalog entry points at the workspace that published it — that workspace owns the Salesforce credentials and the authorized-agents allowlist. Because this is a tenant-context connector, your agent must still be allowlisted in that publishing workspace (or it must have Allow all agents enabled), even though the capability is shared org-wide. Ask the workspace owner to allow your agent, or use Option B to run it from your own workspace.
Running the connector from your own workspace is the security-preferred mode: the Connected App credentials, the per-user OAuth tokens and the authorized-agents allowlist are all scoped to your workspace. You get least-privilege isolation instead of sharing a broad org-wide surface whose credentials and allowlist someone else controls.
1

Install and configure the connector in your workspace

Follow the Workspace builder tab: install Salesforce in your workspace, open its Configuration app, choose the auth mode and provide the Connected App credentials (and connect a Salesforce account for the per-user OAuth mode).
2

Allowlist your agent

In that workspace’s config app, open Authorized agents and tick your agent (the per-agent Install capability button does this for you), or enable Allow all agents.
3

Add the MCP capability to your agent

In your agent, add a capability pointing at your workspace’s MCP Endpoint URL, and set its Scope to:
context_id,agent_id,user_id
The agent_id is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit “agent could not be identified” message. This Scope is separate from the Salesforce OAuth scopes.
4

Connect a Salesforce account (per-user OAuth mode)

In the oauth mode, an unconnected user is prompted to sign in on the first tool call — Agent Factory surfaces a connect_url, or the user can click Connect in the config app. The jwt, clientCredentials and accessToken modes need no per-user sign-in.
The config app exposes two distinct publish buttons. The per-agent Install capability button wires the connector into one specific agent (and allowlists it). The org-wide Add to catalog button (owners/admins only) publishes Salesforce to the Capabilities catalog so any builder can attach it — that is Option A above.

Brief the agent in its system prompt

Wiring the capability is not enough — the agent must know the MCP exists and when to use it. Copy-pasteable starter:
You have access to the Salesforce MCP server. Use it whenever the user asks something that maps to Salesforce data — listing, searching, reading, creating, updating or deleting records, running SOQL/SOSL queries, submitting approval requests, running reports or kicking off Bulk API jobs. Each tool takes an `action` argument selecting the concrete operation. Always prefer calling a tool over guessing from prior context, and confirm with the user before any destructive action (delete, bulk update, metadata deploy).
Refine the trigger keywords (sObject names, business domains, typical user phrasings) so the agent reliably picks up the right intent in your context.
Legacy AI Knowledge agents (no native MCP picker): add the connector under Advanced > Tools > MCP and paste the MCP Endpoint URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its agent_id.
Restricting to read-only (least privilege). Salesforce tools cover both reads and writes (create/update/delete records). Unlike scope-granular providers, Salesforce OAuth uses the broad api scope and does not express read-only at the scope level — object- and field-level access is governed by the connected user’s Profile and Permission Sets in Salesforce. To allow only read access, back the connection (the user who clicks Connect, or the clientCredentials / jwt integration user) with a Salesforce user whose permissions grant Read but not Create/Edit/Delete on the relevant objects. Write calls are then rejected by Salesforce with an INSUFFICIENT_ACCESS / 403 error. This restriction lives in Salesforce, outside any tenant’s reach — the hardest of the guarantees.

Available Tools

Each dispatcher tool takes an action argument that selects the underlying Salesforce operation; only the arguments relevant to the chosen action need to be passed.

Records & Queries

ToolDescription
recordsCRUD on individual records (one per call). Actions: create, get, getField, update, upsert, delete, getDeleted, getUpdated.
querySOQL queries, SOSL searches, parameterized search and pagination. Actions: soql, soqlAll, sosl, parameterizedSearch, next.
compositeRecordsBulk records via the composite/sobjects collection — up to 200 writes (2000 reads). Actions: createMany, createManyForType, updateMany, upsertManyForType, deleteMany, getMany.
compositeComposite endpoints — ordered sub-requests, batch, graph, parent+children tree. Actions: request, batch, graph, tree.

Discovery & Metadata

ToolDescription
versionsREST API versions, available resources, org limits and recent items. Actions: listVersions, listResources, getLimits, getRecent.
sobjectssObject metadata — global list or per-object describe. Actions: describeGlobal, describe, describeBasic.

Bulk API 2.0

ToolDescription
bulkIngestBulk API 2.0 ingest jobs (CSV insert/update/upsert/delete). Actions: create, uploadData, update, get, list, getSuccessful, getFailed, getUnprocessed, delete.
bulkQueryBulk API 2.0 query jobs (async SOQL, CSV results). Actions: create, get, list, getResults, update, delete.

Automation & Analytics

ToolDescription
toolingTooling API — query/CRUD metadata (ApexClass, CustomField, FlexiPage…), run Apex, completions. Actions: query, describeGlobal, describeSObject, createRecord, getRecord, updateRecord, deleteRecord, executeAnonymous, completions, runTestsSync, runTestsAsync.
processProcess rules and approval processes. Actions: listRules, listRulesForObject, triggerRule, listApprovals, submitApproval.
quickActionsOrg / object quick actions. Actions: list, describe, invoke.
analyticsReports & dashboards. Actions: listReports, describeReport, runReport, getReportInstance, listReportInstances, listDashboards, describeDashboard, runDashboard, getDashboardStatus.
metadataMetadata REST deploy. Actions: deploy, getDeployStatus.

Output Formats

Every tool accepts an outputFormat argument that controls the MCP response shape:
  • verbose (default) — human-readable text optimized for LLM consumption
  • structured — concise machine-readable JSON in structuredContent
  • both — both text and structured content

Tool Details

records

CRUD on individual Salesforce records. One record per call. Pick the operation via action; pass record fields nested inside body (Salesforce field API names are case-sensitive).
{
  "name": "records",
  "arguments": {
    "action": "create",
    "sObjectName": "Lead",
    "body": {
      "FirstName": "Georges",
      "LastName": "Abitbol",
      "Company": "La Classe Américaine",
      "Email": "georges.abitbol@example.com"
    }
  }
}
ParameterRequiredDescription
actionYesOne of create, get, getField, update, upsert, delete, getDeleted, getUpdated.
sObjectNameYesAPI name of the sObject (Account, Contact, Lead, Opportunity, My_Custom_Object__c, …).
recordIdFor get/getField/update/deleteSalesforce 15- or 18-char record ID.
bodyFor create/update/upsertObject whose keys are Salesforce field API names.
externalIdField, externalIdValueFor upsertExternal ID field API name and value.
fieldNameFor getFieldAPI name of a single field to fetch (incl. blob/document body).
fieldsFor getComma-separated list of fields to return.
start, endFor getDeleted/getUpdatedISO 8601 time window.

query

Read with SOQL (database language), SOSL (cross-object text search) or a structured parameterized search. Use next with a queryLocator returned by a previous SOQL response to page through large result sets.
{
  "name": "query",
  "arguments": {
    "action": "soql",
    "q": "SELECT Id, Name, AnnualRevenue FROM Account WHERE Industry = 'Technology' ORDER BY AnnualRevenue DESC LIMIT 50"
  }
}
ParameterRequiredDescription
actionYesOne of soql, soqlAll, sosl, parameterizedSearch, next.
qFor soql/soqlAll/soslSOQL or SOSL string.
queryLocatorFor nextLocator returned by the previous SOQL call (nextRecordsUrl).
bodyFor parameterizedSearchStructured search request.

compositeRecords

Multi-record CRUD via the composite/sobjects collection — up to 200 records per call (2000 for reads), with optional allOrNone transactional semantics.
{
  "name": "compositeRecords",
  "arguments": {
    "action": "createManyForType",
    "sObjectName": "Contact",
    "body": {
      "allOrNone": true,
      "records": [
        { "attributes": { "type": "Contact" }, "FirstName": "Jean", "LastName": "Dupont", "Email": "jean.dupont@example.com" },
        { "attributes": { "type": "Contact" }, "FirstName": "Marie", "LastName": "Martin", "Email": "marie.martin@example.com" }
      ]
    }
  }
}
ParameterRequiredDescription
actionYesOne of createMany, createManyForType, updateMany, upsertManyForType, deleteMany, getMany.
sObjectNameFor createManyForType/upsertManyForType/getManyAPI name of the sObject.
bodyFor all writes{ allOrNone, records, externalIdField? }.
idsFor deleteMany/getManyComma-separated record IDs.
fieldsFor getManyComma-separated list of fields.

bulkIngest

Asynchronous high-volume writes via Bulk API 2.0. The typical lifecycle is createuploadData (CSV) → update (state: UploadComplete) → poll get until state=JobCompletegetSuccessful / getFailed.
{
  "name": "bulkIngest",
  "arguments": {
    "action": "create",
    "body": {
      "object": "Contact",
      "operation": "insert",
      "contentType": "CSV",
      "lineEnding": "LF"
    }
  }
}
ParameterRequiredDescription
actionYesOne of create, uploadData, update, get, list, getSuccessful, getFailed, getUnprocessed, delete.
jobIdFor everything but create/listJob ID returned by create.
bodyFor create/updateCreate payload or { state: UploadComplete | Aborted }.
rawBodyFor uploadDataRaw CSV body (Content-Type: text/csv).

analytics

Run reports and dashboards asynchronously, then fetch the resulting report instance. Reports return both the metadata and the row-level facts when includeDetails=true.
{
  "name": "analytics",
  "arguments": {
    "action": "runReport",
    "reportId": "00O5g00000F1234EAA",
    "includeDetails": true
  }
}
ParameterRequiredDescription
actionYesOne of listReports, describeReport, runReport, getReportInstance, listReportInstances, listDashboards, describeDashboard, runDashboard, getDashboardStatus.
reportIdFor report actionsSalesforce report ID.
dashboardIdFor dashboard actionsSalesforce dashboard ID.
instanceIdFor getReportInstanceAsync report instance ID.
includeDetailsNoInclude row-level details in the response.

tooling

Tooling API for metadata-as-data: query/CRUD on ApexClass, CustomField, FlexiPage, ValidationRule, …, plus running Apex (sync, async tests, anonymous execution) and code completions.
{
  "name": "tooling",
  "arguments": {
    "action": "executeAnonymous",
    "anonymousBody": "System.debug('Hello from Apex anonymous');"
  }
}
ParameterRequiredDescription
actionYesSee the Tooling API tool above.
sObjectNameFor Tooling sObject opsTooling API sObject name.
recordIdFor getRecord/updateRecord/deleteRecordTooling record ID.
qFor queryTooling SOQL string.
anonymousBodyFor executeAnonymousApex source to execute as the current user.
bodyFor test runs / record mutationsOperation payload (tests, classNames, …).

Error Handling

HTTP StatusErrorSolution
400Bad RequestMalformed SOQL, invalid field API name, missing required field. Inspect the fields/errorCode array returned by Salesforce.
401UnauthorizedAccess token expired or revoked. Reconnect (per-user OAuth mode) or re-check the JWT / client-credentials configuration.
403ForbiddenThe Salesforce profile lacks API access or object/field-level permissions.
404Not FoundsObject name or record ID does not exist. Note that sObject API names are case-sensitive.
422ValidationValidation rules, picklist constraints or required-field errors on the sObject.
429Rate LimitedOrg API limit reached (DailyApiRequests). Inspect usage via versions action=getLimits and back off.
500Server ErrorTransient Salesforce error. Retry with exponential backoff.

Common Issues

“This agent is not authorized to use this connector” — The calling agent is not in the allowlist. Open the configuration app → Authorized agents → tick this agent (or enable Allow all agents) and Save. This applies even when the agent attached the capability from the org Capabilities catalog: the catalog entry points at a workspace that still owns the allowlist. “The calling agent could not be identified” — The MCP capability Scope does not declare agent_id, so Agent Factory never injects the agent identity. Set the Scope to context_id,agent_id,user_id on the capability, then allow the agent in the config app. “Salesforce is not configured for this workspace” — No auth mode / credentials set. Open the configuration app and provide the Connected App credentials (JWT Bearer, client credentials, OAuth client, or a direct access token). “Salesforce is not connected for this user” — In the per-user oauth mode, no token exists for the current user. Click Connect in the config app, or use the agent’s connect flow. “Salesforce token refresh failed … must reconnect” — The stored refresh token was revoked or expired. The user must reconnect from the config app (OAuth mode). “Forbidden — you need catalog write rights in this org” — The Add to catalog button is only available to org owners/admins, and the org-wide catalog write is gated on that role. Ask an org owner/admin to publish the capability, or wire your agent from your own workspace (Option B in the Agent builder tab). redirect_uri_mismatch at callback time — The auto-computed OAuth Redirect URI shown in the config app must be pasted verbatim into the Connected App’s Callback URL field, including the path. Sandbox vs production hosts also matter: use https://test.salesforce.com as the login host for sandboxes. invalid_grant on JWT Bearer — The runtime user is not pre-authorized for the Connected App, the private key does not match the uploaded certificate, or Use digital signatures is not enabled on the Connected App.

External Resources

Salesforce REST API

Official Salesforce REST API documentation (v62.0).

Tool Agents

Learn how Agent Factory agents consume MCP tools in Prisme.ai.