Salesforce

Salesforce has two modes:

Mode	Provides
Sync + optional MCP	Indexes CRM records, mirrors Salesforce sharing, and can provide native actions plus live MCP actions
MCP only	Provides live MCP actions with each user’s Salesforce identity; no Salesforce records are synced or indexed

Choose MCP only for live Salesforce queries and actions without an Omni record index. Choose Sync + optional MCP for indexed search, inherited Salesforce permissions, search operators, native actions, and optional MCP.

Overview

Synced records

Sync-enabled sources index:

Object	Content
Accounts	Company profile, industry, billing location, revenue, owner
Contacts	Name, email, phone, title, department, parent account
Opportunities	Amount, stage, close date, probability, type, lead source, parent account
Leads	Name, company, status, industry, lead source, owner
Cases	Case number, subject, status, priority, type, origin, account, contact
Tasks	Subject, status, priority, activity date, related records

Sync also reads User, Group, GroupMember, UserRole, and the relevant *Share tables to resolve permissions. Deleted records are reconciled from Salesforce’s deleted-records API. Salesforce users appear in Omni’s people directory; CRM records are documents.

Permissions

For sync-enabled sources, Omni mirrors:

Ownership: owners, including queue members, receive access.
Role hierarchy: with Grant Access Using Hierarchies, ancestor roles of the owner receive access.
Shares: user, group, and role grants from the per-object share tables are expanded.
Org-wide defaults: only configured public-read objects are public; other records are private by default.

Only active Salesforce users with email addresses receive grants. The default permission settings are sync_users, sync_groups, sync_shares, and grant_access_using_hierarchies. Disabling sync_users also disables sharing and hierarchy resolution. MCP-only does not copy records or sharing data into Omni. Each user needs API Enabled and the object, field, and record permissions required by that user’s live queries or actions.

Prerequisites

All modes require:

Omni with the Salesforce connector service running (salesforce connector).
Salesforce administrator access to create an External Client App and configure its policies.

Any setup that enables MCP also requires this callback, using the public Omni base URL:

https://<your-omni-domain>/api/oauth/callback

For local Omni, use its local base URL with the same /api/oauth/callback path. MCP authorization also requires a setup administrator or permitted Salesforce user who can complete OAuth. Sync-enabled sources additionally require a dedicated integration user with a full Salesforce user license, a permission set with the sync permissions below, and a secure location for an RSA private key.

Setup

Each tab is a complete workflow. Do not combine steps between tabs.

MCP only
Sync + optional MCP

Step 1: Create the External Client App

In Salesforce, open Apps → External Client Apps → External Client App Manager → New External Client App.
Name it Omni, provide a contact email, and keep distribution Local.
Enable OAuth and set the callback to https://<your-omni-domain>/api/oauth/callback.
Save the generated Client ID/Consumer Key and Client Secret. Omni is a server-side confidential client; retain secret-required settings for authorization-code/web-server exchange if Salesforce presents them.
Enable Authorization Code and Credentials Flow and Require Proof Key for Code Exchange (PKCE).

OAuth permissions

In the External Client App, select these Salesforce permissions:

Access unique user identifiers
Access the identity URL service
Manage user data via APIs
Perform requests at any time

These permissions let Omni identify users, call Salesforce APIs, and maintain MCP authorization. Do not select Manage user data via Web browsers or Access Salesforce hosted MCP servers; Omni does not require them. Configure policies so the setup administrator and intended Salesforce users can authorize the app; preauthorize them if the org uses admin-approved users.MCP only does not require JWT Bearer Flow, an integration user, certificate, private key, instance URL, or sync interval.

Step 2: Create the Omni source

Open Admin Settings → Integrations → Connect Salesforce.
Select MCP only.
Enter the External Client App’s Client ID, Client Secret, and Login URL: https://login.salesforce.com for production or https://test.salesforce.com for a sandbox.
Select Connect.

The form has no instance URL, JWT, certificate, private-key, or sync-interval field. No Salesforce records are synced or indexed.

Step 3: Authorize the setup administrator

After you select Connect, Omni immediately redirects your browser to Salesforce. Complete these actions in Salesforce:

Sign in as the setup administrator.
Confirm that you are authorizing the Salesforce organization this Omni source should represent.
Approve the requested OAuth scopes and return to Omni.

Omni saves this administrator credential for the Salesforce source, uses it to establish the organization’s binding, and discovers the MCP catalog. Setup is complete only when the redirect returns to Omni and catalog discovery succeeds. Salesforce supplies instance information in the OAuth response; you do not enter an instance URL.

Step 4: Authorize users

Every Omni user invoking MCP authorizes their own Salesforce identity. The setup administrator is the first user; later users authorize on first MCP use:

Start an MCP action in chat.
Follow the Salesforce redirect, sign in, complete MFA if requested, approve scopes, and return to Omni.
Ensure that user has API Enabled and the object, field, and record permissions required by the live action.

Credentials and Salesforce permissions remain per user. Omni does not use the setup administrator’s credential for another user. Revoked, expired, missing, or wrong-organization credentials must be authorized again.

Sync step 1: Create the integration user

In Salesforce, open Setup → Users → Users → New User.
Create a dedicated user such as Omni Salesforce Integration.
Use a full Salesforce user license. The Salesforce Integration license cannot provide the role-hierarchy and user-visibility permissions native sync needs.
Keep the user active and record its username.

Sync step 2: Grant sync permissions

Create a permission set, for example Omni Connector Read, with no license, then assign it to the integration user. Enable:

Object Settings: Read and View All Records for Account, Contact, Opportunity, Lead, Case, and Task.
System Permissions: API Enabled, View All Data, View Roles and Role Hierarchy, and View All Users.

The connector reads AccountShare, ContactShare, OpportunityShare, LeadShare, and CaseShare through the parent-object and View All Data permissions; these share objects are not granted individually.

If User.UserRoleId is not queryable, role and share resolution fails. Use a full Salesforce license, or disable hierarchy/share resolution with grant_access_using_hierarchies: false and, where necessary, sync_shares: false.

Sync step 3: Generate the JWT key pair

Run outside the repository:

umask 077
openssl genrsa -out privatekey.pem 2048
openssl req -new -x509 \
  -key privatekey.pem \
  -out server.crt \
  -days 3650 \
  -subj "/CN=Omni Salesforce Integration"
chmod 600 privatekey.pem

Keep privatekey.pem secret. Upload only server.crt to Salesforce.

Sync step 4: Create the External Client App

For every sync source:

Open Apps → External Client Apps → External Client App Manager → New External Client App. Name it Omni, provide a contact email, and keep distribution Local.
Obtain the Consumer Key/Client ID.
Enable JWT Bearer Flow and upload server.crt.
Configure policies/preauthorization so the dedicated integration user (or its permitted profile/user) can use the JWT flow. This integration-user policy is required for sync.

A sync-only JWT setup does not require a callback URL, Client Secret, MCP scopes, Authorization Code and Credentials Flow, or PKCE.To add optional MCP to this same app:

Enable OAuth and set https://<your-omni-domain>/api/oauth/callback as the callback.
Retain the generated Client Secret for the server-side authorization-code exchange; retain any secret-required web-server settings Salesforce presents.
Select these Salesforce permissions:
- Access unique user identifiers
- Access the identity URL service
- Manage user data via APIs
- Perform requests at any time
Do not select Manage user data via Web browsers or Access Salesforce hosted MCP servers; Omni does not require them.
Enable Authorization Code and Credentials Flow and PKCE.
Permit intended Salesforce user profiles/users to authorize MCP. The integration user’s JWT policy remains required separately.

Sync step 5: Create the JWT source

Open Admin Settings → Integrations → Connect Salesforce and select External Client App (JWT).
Enter Consumer Key, Private Key (PEM), the integration Username, and Login URL (https://login.salesforce.com for production or https://test.salesforce.com for a sandbox).
Enter the exact Salesforce Instance URL.
Select Connect, keep the source enabled, and configure its sync interval.

The instance URL and JWT credentials bind the sync source. It now provides indexed records and native actions.

The UI also offers Access Token for short-lived native sync/action trials. It expires within hours and cannot itself authenticate per-user MCP; adding MCP requires a separately configured External Client App/OAuth client.

Sync step 6: Optionally configure MCP

If MCP was enabled in Step 4:

Open the Salesforce source under Admin Settings → Integrations.
Select Configure MCP OAuth client.
Enter the same app’s Client ID and Client Secret.
Leave DCR initial access token blank for a pre-created app, then save. Dynamic Client Registration requires an administrator-issued initial access token.

This client is stored for this Salesforce source and is separate from JWT credentials. The source is already bound by its instance URL/JWT setup; no admin-first OAuth is required. The first permitted MCP user can authorize from Authorize Salesforce or the first MCP action, which also discovers the MCP catalog.

Sync step 7: Authorize each MCP user

Every user invoking MCP authorizes their own Salesforce identity. The first MCP user may be any permitted user; later users authorize when they first use MCP:

Start an MCP action in chat.
Follow the Salesforce redirect, sign in, complete MFA if requested, approve scopes, and return to Omni.
Ensure that user has API Enabled and the object, field, and record permissions required by live actions.

If optional MCP was not configured, the JWT source still provides sync, indexed search, and native actions without per-user MCP authorization.

Managing the Integration

Sync-enabled capabilities

These apply only to sync-enabled sources:

Records and status: indexed Salesforce records, sync status, manual sync, and a configurable interval. Changes to synced objects, fields, or permission settings trigger full reconciliation.
Search operators: owner:, status:, priority:, stage:, account:, industry:, and lead_source: filter indexed documents.
Native actions: find_records (read), get_case (read), create_case (write), update_case_status (write), create_task (write), and update_task_status (write). Write actions require confirmation and honor read-only/action authorization.

MCP-only has no sync schedule, manual sync, sync status, or indexed Salesforce records.

MCP actions (both modes)

MCP actions use the local official @salesforce/mcp integration. Omni exposes its discovered tool catalog; each execution uses the invoking user’s OAuth credential, and Salesforce enforces that user’s permissions. The data toolset includes read tools such as get_username, list_all_orgs, and run_soql_query when available. “MCP only” means MCP-origin actions only, not read-only. It excludes native actions and sync, but write-classified MCP actions may still be available subject to confirmation, authorization, and the source’s read-only setting.

Troubleshooting

Sync fails with Account unsupported or UserRoleId not queryable

Check the integration user’s full license, object Read and View All Records, and system permissions from Sync step 2. UserRoleId is required for default hierarchy resolution; use the documented settings only if your license cannot provide it.

MCP tools do not appear

Confirm the source-scoped Client ID/Secret. For MCP-only, the setup administrator must finish the immediate redirect and catalog discovery. For sync-enabled sources, the JWT source must be enabled and the first permitted user must authorize MCP.

MCP authorization binds the wrong organization

MCP-only binding comes from the first administrator’s Salesforce OAuth authorization, not an entered instance URL or JWT. Reauthorize in the intended organization and check the app’s login and callback URLs.

MCP live query returns a permission error

Salesforce evaluates the invoking user’s credential. Grant that user API Enabled and the required object, field, and record permissions; the setup administrator’s permissions do not transfer.

Synced records are missing after permission changes

This is sync-only. Run a manual sync after changing profiles, permission sets, roles, or sharing rules and confirm it completes.

Security Considerations

Sync uses the dedicated integration user’s JWT; MCP uses each user’s OAuth credential. The JWT is never an MCP fallback.
Sync binding uses the configured instance URL and validated JWT credentials. MCP-only binding comes from the first administrator OAuth authorization.
Store private keys, Client Secrets, access/refresh tokens, and MFA codes securely. Omni encrypts source and user credentials at rest.
Limit Salesforce permissions to required sync or live-query work. Read-only settings govern write-capable native and MCP actions; MCP-only is not inherently read-only.

What’s Next

Search Your Data

Search synced CRM records alongside your other sources

Access Control

Understand Salesforce sharing for synced records

Connector Management

Manage sync-enabled sources and integrations

Getting Started

Deployment

Connectors

Developers

User Guide

Administration

Overview

Synced records

Permissions

Prerequisites

Setup

Step 1: Create the External Client App

OAuth permissions

Step 2: Create the Omni source

Step 3: Authorize the setup administrator

Step 4: Authorize users

Sync step 1: Create the integration user

Sync step 2: Grant sync permissions

Sync step 3: Generate the JWT key pair

Sync step 4: Create the External Client App

Sync step 5: Create the JWT source

Sync step 6: Optionally configure MCP

Sync step 7: Authorize each MCP user

Managing the Integration

Sync-enabled capabilities

MCP actions (both modes)

Troubleshooting

Security Considerations

What’s Next

Search Your Data

Access Control

Connector Management

​Overview

​Synced records

​Permissions

​Prerequisites

​Setup

​Step 1: Create the External Client App

​OAuth permissions

​Step 2: Create the Omni source

​Step 3: Authorize the setup administrator

​Step 4: Authorize users

​Sync step 1: Create the integration user

​Sync step 2: Grant sync permissions

​Sync step 3: Generate the JWT key pair

​Sync step 4: Create the External Client App

​Sync step 5: Create the JWT source

​Sync step 6: Optionally configure MCP

​Sync step 7: Authorize each MCP user

​Managing the Integration

​Sync-enabled capabilities

​MCP actions (both modes)

​Troubleshooting

​Security Considerations

​What’s Next

Search Your Data

Access Control

Connector Management

Overview

Synced records

Permissions

Prerequisites

Setup

Step 1: Create the External Client App

OAuth permissions

Step 2: Create the Omni source

Step 3: Authorize the setup administrator

Step 4: Authorize users

Sync step 1: Create the integration user

Sync step 2: Grant sync permissions

Sync step 3: Generate the JWT key pair

Sync step 4: Create the External Client App

Sync step 5: Create the JWT source

Sync step 6: Optionally configure MCP

Sync step 7: Authorize each MCP user

Managing the Integration

Sync-enabled capabilities

MCP actions (both modes)

Troubleshooting

Security Considerations

What’s Next