Spear's AI agent can read your Salesforce data through MCP and use it in chat, scheduled routines and agentic campaign steps. The connection is read-only: the agent can read and query records but cannot create, update or delete them.
Setup takes three steps and usually two people: a Salesforce admin prepares the org (steps 1 and 2), then a Spear org admin connects it (step 3).
Steps 1 and 2 are both required. Without step 1, connecting fails with "Salesforce app not installed". Without step 2, the connection succeeds but the agent gets no Salesforce data.
Before you start
Salesforce: Enterprise, Performance, Unlimited or Developer Edition (Salesforce's hosted MCP servers need Enterprise or above), and an admin who can install packages and manage MCP servers in Setup.
Spear: a Spear org admin, an active paid plan (Starter and above, not the Free Trial) and a desktop browser. Org settings isn't available on mobile.
One Salesforce connection per Spear workspace. Every user's agent reads Salesforce as the one Salesforce user who connected, and connecting again as someone else replaces the connection for everyone. Pick that user on purpose. A dedicated integration user with exactly the access your team should share works well. Salesforce object permissions, field-level security and sharing rules for that user decide what the agent can see.
Step 1: Install the Spear Integration package (Salesforce admin)
Do this once per Salesforce org. A sandbox is a separate org and needs its own install. You don't need to create a Connected App or External Client App yourself.
Sign in to the Salesforce org you want to connect.
Open the install link that matches the org:
Production or Developer Edition: https://login.salesforce.com/packaging/installPackage.apexp?p0=04tJ9000000ge5WIAQ
Sandbox or scratch org: https://test.salesforce.com/packaging/installPackage.apexp?p0=04tJ9000000ge5WIAQ
Choose who to install it for (Install for All Users is fine, or follow your org's policy) and click Install.
In Setup, open External Client App Manager and check that Spear Integration is listed.
Both links install the same package. Only the sign-in page differs, because login.salesforce.com doesn't recognize sandbox orgs.
The package contains the Spear Integration External Client App, its OAuth settings and an empty permission set named MCP Server User. It has no Apex, triggers, objects or data changes.
If Setup > Installed Packages already lists an older beta Spear package, uninstall it first so your org has a single Spear app.
Optional: limit who can authorize Spear. By default, any user in your org can sign in to the Spear Integration app. To restrict it:
Open the app in External Client App Manager and set its OAuth policy Permitted Users to Admin approved users are pre-authorized.
Attach a permission set to the app's policies. The package's empty MCP Server User permission set works.
Assign that permission set to the Salesforce user who will connect.
If you restrict access but skip the assignment, connecting fails with "The connection to Salesforce has failed".
Step 2: Turn on sobject-reads (Salesforce admin)
Do this once per Salesforce org. Salesforce ships every MCP server turned off, and a package can't turn one on.
In Setup, type MCP Servers in Quick Find and select MCP Servers under API Catalog.
Open the Salesforce Servers tab.
Find sobject-reads (API name
platform/sobject-reads) and activate it. Depending on your Salesforce release, it's a toggle in the list or an Activate button on the server's page. It's the only server Spear needs.Wait up to 2 minutes for it to go live.
Activating sobject-reads applies to every MCP client in your org, not only Spear. Each client still reads only what its signed-in user can see.
Step 3: Connect Salesforce in Spear (Spear org admin)
Do this after your Salesforce admin has finished steps 1 and 2.
Go to Org settings > Integrations. You'll find Org settings in the sidebar under Setup (or behind the gear icon in the classic layout).
On the Salesforce card, click Connect.
Connecting a sandbox? Click Using a sandbox org? first. It switches the install link and the sign-in page to test.salesforce.com. If your admin hasn't installed the package yet, Open install link and Copy link give you the link to send them.
Click Connect Salesforce, sign in to Salesforce and approve access. Spear asks Salesforce to show its sign-in screen even if you're already signed in elsewhere, so you can pick the account. Sign in as the Salesforce user the whole workspace should read as.
When sign-in finishes, the window closes and the Salesforce card shows Manage integration. The window also closes if sign-in fails or you close the Salesforce popup, so look for Manage integration instead of relying on the window closing.
Click Manage integration. In General settings, check that Connect our AI agent to your CRM reads Enabled. It's on by default after a new connection. If you change it, click Save. Saved changes reach the agent within a minute or two.
If it says Action needed, hover over the toggle. The tooltip names what's missing (see the table below).
Connected Salesforce before mid-May 2026?
Workspaces that connected earlier may still be on Spear's older connector. You'll see the AI toggle greyed out with "Reconnect Salesforce to enable this connection". To fix it:
Ask your Salesforce admin to finish steps 1 and 2 first. Reconnecting uses the Spear Integration app. If it isn't installed, the reconnect fails and exports stay paused until you're connected again.
In Manage integration > General settings, click Disconnect. If Spear asks what to do with synced excluded companies, choose Keep and disconnect.
Close the window and repeat step 3.
Your object mappings, export settings, excluded-companies setup and the AI toggle setting are kept. Companies synced from Salesforce sync again after you reconnect. If you had switched the AI toggle off before, it stays off: turn it on and click Save.
If the card shows a Reconnect needed badge, just click Reconnect on the card instead. You don't need to disconnect first.
Verify it works
Open a chat with the Spear agent and try:
"Ask Salesforce who I am signed in as." It should name the Salesforce user from step 3. This works even in an empty org, and it shows whose permissions every agent in your workspace is using.
"List 5 open Opportunities from Salesforce with their account name and stage." It should return real records.
What the agent can read
Any standard or custom object the connecting user can read. Through sobject-reads, the agent can look up object schemas, run SOQL queries, search across objects, check the current user, list recently viewed records and follow related records. To narrow what it sees, change that user's Salesforce permission sets and sharing rules.
Reading the AI toggle
Spear checks the live connection to Salesforce every time you open the settings window or come back to the browser tab. The label and tooltip are the quickest way to see what's wrong.
Label | What it means | What to do |
Enabled | The agent can read Salesforce. | Nothing. |
Checking… | Spear is testing the connection. | Wait a moment. |
Action needed: "Your Salesforce admin must enable sobject-reads…" | sobject-reads is off or still activating. It can also mean the app was installed recently or the connecting user lacks API access. | Salesforce admin: do step 2. If it persists, wait up to 30 minutes after the install and confirm the user has API access, then Disconnect and Connect again. |
Action needed: "Your Salesforce connection expired…" | Spear can't renew the Salesforce sign-in. This is occasionally a temporary error. | Reopen the window once. If it persists, Disconnect and Connect again. |
Action needed: "Couldn't reach the Salesforce MCP server…" | A temporary network error, the Salesforce card's switch is off, or the subscription isn't active. | Try again in a minute and check the card's switch is on. |
Disabled, greyed out | The workspace is on the older connector. | See "Connected Salesforce before mid-May 2026?" above. |
Disabled | The agent was switched off for Salesforce. | Turn it on and click Save. |
You can't change the toggle while Spear can't reach Salesforce's MCP server. To stop agent access in that state, switch off the Salesforce card on the Integrations tab or click Disconnect.
Troubleshooting
Spear doesn't email you when the connection breaks. Check the AI toggle in the Salesforce settings window first.
"Salesforce app not installed": the package isn't installed in the org you signed in to. Do step 1 with the matching link (for a sandbox, also select Using a sandbox org?), then click Connect Salesforce again.
Install link says the package isn't available: you used the production link for a sandbox or the other way round. Use login.salesforce.com for production and Developer Edition, test.salesforce.com for sandbox and scratch orgs.
"You don't have permission": only Spear org admins can connect, disconnect or save these settings.
Connect does nothing: the workspace is on the Free Trial plan or its subscription isn't active.
"The connection to Salesforce has failed": the Salesforce popup was closed, sign-in failed, or your Salesforce admin restricted who can use the Spear Integration app and the connecting user wasn't assigned the permission set. Try again or ask your admin to assign it.
Chat says "Salesforce isn't responding, so this answer doesn't include your CRM data": sobject-reads is off or still activating. Do step 2, wait 2 minutes, then reopen the settings window.
The agent says Salesforce isn't connected, or tells you to connect it: the AI toggle is off, the Salesforce card is switched off, the workspace is on the older connector or the Salesforce sign-in expired. Open Manage integration, read the toggle's label and tooltip, and fix what it names.
It worked before and now doesn't: the sign-in expired or was revoked (a password or permission change, your app's refresh-token policy, revoked tokens), or sobject-reads was turned off. Check the toggle and follow its tooltip.
The agent can't see a specific record or field: the connecting Salesforce user lacks object access, field-level security or sharing. Grant it in Salesforce. No reconnect needed.
MCP Servers doesn't appear in Setup: check your Salesforce edition, then ask Salesforce Support to enable the MCPService permission for your org.
A setting change doesn't show in chat right away: Spear refreshes the agent's connections about once a minute. Send another message after a minute or two.
FAQ
Can Spear write to our Salesforce? The agent itself can't. It reads through sobject-reads. The same Salesforce connection is also used by Spear's CRM features, and some of those write: exporting prospects, the Test button in Object mapping, creating the Spear Prospect ID field, and syncing conversation details into mapped fields. See How to integrate Spear to Salesforce for those.
What does the AI toggle control? Only the agent's Salesforce record reads. Exports and CRM settings keep working, and the agent can still look up field names and picklist values and export prospects through Spear's own CRM features. To stop all Salesforce use, switch off the Salesforce card or Disconnect.
Does this use our Salesforce API limits? Yes. Agent requests count toward your daily API request limit. Check usage in Setup > Company Information > API Requests, Last 24 Hours.
Does Salesforce charge for hosted MCP servers? Salesforce says hosted MCP servers are meant for customers with Flex Credits and usage may be billed. Check the current terms with your Salesforce account team.
Can we connect a sandbox? Yes. Repeat steps 1 and 2 in the sandbox with the sandbox install link, then connect with Using a sandbox org? selected. Spear sends agent requests to Salesforce's sandbox endpoint automatically. Connecting a sandbox replaces a production connection, since there is one connection per workspace.
Our org blocks sign-in from login.salesforce.com. Will this work? Spear signs in through login.salesforce.com (test.salesforce.com for sandboxes). If your org blocks those, talk to your Spear account manager before connecting.
How do we disconnect? In Spear, go to Manage integration > General settings > Disconnect. This stops all Spear use of Salesforce and keeps your settings for a later reconnect. It doesn't revoke the sign-in on the Salesforce side. In Salesforce, revoke the Spear Integration app's OAuth tokens in Setup or uninstall the package from Installed Packages. Turning off sobject-reads stops agent reads for every MCP client in your org, but Spear's exports keep working.