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’sclient_credentialsgrant, 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_accessselected on the Connected App. - The Login Host matching the org type:
https://login.salesforce.comfor production / Developer Edition,https://test.salesforce.comfor sandbox, or a custom My Domain host likehttps://<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).
Platform admin (Governance) — one-time platform setup
Platform admin (Governance) — one-time platform setup
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.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.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:The
agent_id in the scope is what lets the connector identify and authorize the calling agent.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).
- Agent builder (Agent Factory)
- Workspace builder (DSUL)
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).
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 Scopecontext_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.
Option B — Run it from your own workspace (recommended)
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).
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.
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: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.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: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 anaction argument that selects the underlying Salesforce operation; only the arguments relevant to the chosen action need to be passed.Records & Queries
| Tool | Description |
|---|---|
records | CRUD on individual records (one per call). Actions: create, get, getField, update, upsert, delete, getDeleted, getUpdated. |
query | SOQL queries, SOSL searches, parameterized search and pagination. Actions: soql, soqlAll, sosl, parameterizedSearch, next. |
compositeRecords | Bulk records via the composite/sobjects collection — up to 200 writes (2000 reads). Actions: createMany, createManyForType, updateMany, upsertManyForType, deleteMany, getMany. |
composite | Composite endpoints — ordered sub-requests, batch, graph, parent+children tree. Actions: request, batch, graph, tree. |
Discovery & Metadata
| Tool | Description |
|---|---|
versions | REST API versions, available resources, org limits and recent items. Actions: listVersions, listResources, getLimits, getRecent. |
sobjects | sObject metadata — global list or per-object describe. Actions: describeGlobal, describe, describeBasic. |
Bulk API 2.0
| Tool | Description |
|---|---|
bulkIngest | Bulk API 2.0 ingest jobs (CSV insert/update/upsert/delete). Actions: create, uploadData, update, get, list, getSuccessful, getFailed, getUnprocessed, delete. |
bulkQuery | Bulk API 2.0 query jobs (async SOQL, CSV results). Actions: create, get, list, getResults, update, delete. |
Automation & Analytics
| Tool | Description |
|---|---|
tooling | Tooling API — query/CRUD metadata (ApexClass, CustomField, FlexiPage…), run Apex, completions. Actions: query, describeGlobal, describeSObject, createRecord, getRecord, updateRecord, deleteRecord, executeAnonymous, completions, runTestsSync, runTestsAsync. |
process | Process rules and approval processes. Actions: listRules, listRulesForObject, triggerRule, listApprovals, submitApproval. |
quickActions | Org / object quick actions. Actions: list, describe, invoke. |
analytics | Reports & dashboards. Actions: listReports, describeReport, runReport, getReportInstance, listReportInstances, listDashboards, describeDashboard, runDashboard, getDashboardStatus. |
metadata | Metadata REST deploy. Actions: deploy, getDeployStatus. |
Output Formats
Every tool accepts anoutputFormat argument that controls the MCP response shape:verbose(default) — human-readable text optimized for LLM consumptionstructured— concise machine-readable JSON instructuredContentboth— both text and structured content
Tool Details
records
CRUD on individual Salesforce records. One record per call. Pick the operation viaaction; pass record fields nested inside body (Salesforce field API names are case-sensitive).| Parameter | Required | Description |
|---|---|---|
action | Yes | One of create, get, getField, update, upsert, delete, getDeleted, getUpdated. |
sObjectName | Yes | API name of the sObject (Account, Contact, Lead, Opportunity, My_Custom_Object__c, …). |
recordId | For get/getField/update/delete | Salesforce 15- or 18-char record ID. |
body | For create/update/upsert | Object whose keys are Salesforce field API names. |
externalIdField, externalIdValue | For upsert | External ID field API name and value. |
fieldName | For getField | API name of a single field to fetch (incl. blob/document body). |
fields | For get | Comma-separated list of fields to return. |
start, end | For getDeleted/getUpdated | ISO 8601 time window. |
query
Read with SOQL (database language), SOSL (cross-object text search) or a structured parameterized search. Usenext with a queryLocator returned by a previous SOQL response to page through large result sets.| Parameter | Required | Description |
|---|---|---|
action | Yes | One of soql, soqlAll, sosl, parameterizedSearch, next. |
q | For soql/soqlAll/sosl | SOQL or SOSL string. |
queryLocator | For next | Locator returned by the previous SOQL call (nextRecordsUrl). |
body | For parameterizedSearch | Structured search request. |
compositeRecords
Multi-record CRUD via thecomposite/sobjects collection — up to 200 records per call (2000 for reads), with optional allOrNone transactional semantics.| Parameter | Required | Description |
|---|---|---|
action | Yes | One of createMany, createManyForType, updateMany, upsertManyForType, deleteMany, getMany. |
sObjectName | For createManyForType/upsertManyForType/getMany | API name of the sObject. |
body | For all writes | { allOrNone, records, externalIdField? }. |
ids | For deleteMany/getMany | Comma-separated record IDs. |
fields | For getMany | Comma-separated list of fields. |
bulkIngest
Asynchronous high-volume writes via Bulk API 2.0. The typical lifecycle iscreate → uploadData (CSV) → update (state: UploadComplete) → poll get until state=JobComplete → getSuccessful / getFailed.| Parameter | Required | Description |
|---|---|---|
action | Yes | One of create, uploadData, update, get, list, getSuccessful, getFailed, getUnprocessed, delete. |
jobId | For everything but create/list | Job ID returned by create. |
body | For create/update | Create payload or { state: UploadComplete | Aborted }. |
rawBody | For uploadData | Raw 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 whenincludeDetails=true.| Parameter | Required | Description |
|---|---|---|
action | Yes | One of listReports, describeReport, runReport, getReportInstance, listReportInstances, listDashboards, describeDashboard, runDashboard, getDashboardStatus. |
reportId | For report actions | Salesforce report ID. |
dashboardId | For dashboard actions | Salesforce dashboard ID. |
instanceId | For getReportInstance | Async report instance ID. |
includeDetails | No | Include row-level details in the response. |
tooling
Tooling API for metadata-as-data: query/CRUD onApexClass, CustomField, FlexiPage, ValidationRule, …, plus running Apex (sync, async tests, anonymous execution) and code completions.| Parameter | Required | Description |
|---|---|---|
action | Yes | See the Tooling API tool above. |
sObjectName | For Tooling sObject ops | Tooling API sObject name. |
recordId | For getRecord/updateRecord/deleteRecord | Tooling record ID. |
q | For query | Tooling SOQL string. |
anonymousBody | For executeAnonymous | Apex source to execute as the current user. |
body | For test runs / record mutations | Operation payload (tests, classNames, …). |
Error Handling
| HTTP Status | Error | Solution |
|---|---|---|
| 400 | Bad Request | Malformed SOQL, invalid field API name, missing required field. Inspect the fields/errorCode array returned by Salesforce. |
| 401 | Unauthorized | Access token expired or revoked. Reconnect (per-user OAuth mode) or re-check the JWT / client-credentials configuration. |
| 403 | Forbidden | The Salesforce profile lacks API access or object/field-level permissions. |
| 404 | Not Found | sObject name or record ID does not exist. Note that sObject API names are case-sensitive. |
| 422 | Validation | Validation rules, picklist constraints or required-field errors on the sObject. |
| 429 | Rate Limited | Org API limit reached (DailyApiRequests). Inspect usage via versions action=getLimits and back off. |
| 500 | Server Error | Transient 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 declareagent_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.