Connecting an AI Agent to Salesforce: APIs, MCP and Agentforce
There are three ways to give an AI agent access to Salesforce: the REST API with SOQL, the MCP servers that Salesforce now hosts, or Agentforce, Salesforce's own agent layer. The right choice depends less on the model than on one question: does the agent act for a person who is signed in, or does it run unattended? This overview, current as of November 2026, sorts the options.
What does connecting an AI agent to Salesforce actually involve?
Connecting means an agent running outside Salesforce can read, search and selectively update records, with tightly scoped permissions. Typical jobs are summarising opportunities, preparing account briefs before a meeting, logging activities or triaging service cases. Salesforce stays the system of record for customer data.
The agent itself runs in your environment, uses a model you choose and combines Salesforce with other sources such as your ERP, ticketing tool, document store or mailbox. That is the main difference from Agentforce, which runs inside the Salesforce platform. If you want to know what such an agent should do for a sales team, the AI sales agent guide covers the use cases; this article is about the plumbing.
Teams on HubSpot face the same core question with different building blocks: Connecting an AI Agent to HubSpot covers service keys and HubSpot's MCP server. Salesforce adds two twists you will not meet there: the move from Connected Apps to External Client Apps, and a hard line between per-user MCP access and server-to-server access.
How does the integration work? The building blocks
Every Salesforce integration has four parts: an app registered in Salesforce, an OAuth flow that issues the access token, an interface (REST API or MCP server), and a user context whose permissions the agent inherits. Choose these four deliberately and most of your architecture is settled.
External Client Apps replace Connected Apps
Any external program calling the REST API needs a registered app with OAuth settings. For years that meant a Connected App. According to the REST API Developer Guide, creating new Connected Apps has been restricted since Spring ’26: existing apps keep working, exceptions go through Support, and External Client Apps are recommended instead. Salesforce calls them the new generation, designed to improve security and fix packaging and distribution issues.
For a new agent project, start with an External Client App. For Hosted MCP Servers it is mandatory anyway: the setup guide states that Connected Apps are not supported there.
OAuth flows: a person or an integration user
The OAuth flow decides whose identity the agent uses. With the authorization code flow a person signs in through the browser and the agent inherits that person's access. With the client credentials flow the app exchanges its consumer key and secret for a token that runs as a named integration user.
Salesforce positions client credentials as a more secure alternative to the username-password flow. Three details from the documentation matter for agents:
- No refresh tokens. When the token expires, the agent requests a new one.
- Calls to
login.salesforce.comandtest.salesforce.comare not supported; use your org's My Domain URL. - Anyone holding the key and secret can obtain a token, so rotate the secret regularly and immediately if it leaks.
REST API and SOQL
The REST API is the general-purpose route to records. Reads usually go through the Query resource at /services/data/vXX.X/query?q=… with a SOQL statement. One synchronous response holds up to 2,000 records, fewer for complex ones; when done is false, the agent follows nextRecordsUrl for the next batch.
The examples in Salesforce's documentation currently use API version v68.0 (as of November 2026). Pin the version in your integration rather than discovering it at runtime, so a release does not quietly change behaviour.
# Minimal sketch: token via client credentials, then a SOQL query
import os
import requests
base = os.environ["SF_MY_DOMAIN_URL"] # e.g. https://yourcompany.my.salesforce.com
token = requests.post(
f"{base}/services/oauth2/token",
data={
"grant_type": "client_credentials",
"client_id": os.environ["SF_CONSUMER_KEY"],
"client_secret": os.environ["SF_CONSUMER_SECRET"],
},
timeout=30,
).json()["access_token"]
soql = "SELECT Id, Name, StageName, CloseDate FROM Opportunity WHERE IsClosed = false"
url = f"{base}/services/data/v68.0/query"
params = {"q": soql}
records = []
while url:
r = requests.get(url, params=params,
headers={"Authorization": f"Bearer {token}"}, timeout=30)
r.raise_for_status()
body = r.json()
records += body["records"]
# follow-up pages via nextRecordsUrl, no parameters
url = base + body["nextRecordsUrl"] if not body["done"] else None
params = None
print(len(records), "open opportunities")
The sketch follows the endpoints in Salesforce's documentation: the token endpoint from the client credentials help article, paging from Execute a SOQL Query. In an agent, this becomes a named tool ("read open opportunities") that the model calls, instead of letting the model write free-form SOQL.
Hosted MCP Servers
Salesforce now runs its own MCP servers. Any MCP-capable client, which Salesforce lists as Claude, ChatGPT, Cursor or a custom agent, can connect and act on behalf of authorised users. Server URLs look like https://api.salesforce.com/platform/mcp/v1/platform/sobject-all, with variants for My Domain and sandboxes.
The standard servers are split by permission: sobject-all (full create, read, update, delete), sobject-reads (read only), sobject-mutations (create and update, no delete) and sobject-deletes. Product servers cover areas such as Data 360 and Tableau Next. All standard servers ship disabled and need an admin to switch them on.
The External Client App needs the mcp_api and refresh_token scopes and JWT-based access tokens. Salesforce notes that a new app can take up to 30 minutes to become usable, so allow for that before you start debugging your configuration.
Which option fits which situation?
You have three options: your own agent on the REST API, a client or agent on Hosted MCP, and Agentforce. They are not mutually exclusive. What decides it is the user context, how much data lives outside Salesforce, and where you want the model and logic to run.
| Criterion | REST API + SOQL | Hosted MCP Servers | Agentforce |
|---|---|---|---|
| Acts as | integration user or signed-in user | signed-in user only | Salesforce user or channel |
| Unattended runs | yes (client credentials) | no | inside Salesforce |
| Custom code | yes | little, configured in Setup | configuration and Agent Script |
| Non-Salesforce data | combine freely | via the client | via Salesforce integrations |
| Billing | org API allocation | Flex Credits, per Salesforce | per your Salesforce contract |
Your own agent on the REST API
Choose this when nobody is watching: an overnight pipeline review, automatic enrichment of new leads, reconciliation with the ERP. You build the tools, decide exactly which fields the agent can see, and connect Salesforce to anything else. The cost is your own code, your own monitoring and a carefully scoped integration user.
A client or agent on Hosted MCP
Choose this when people work in an AI client and need Salesforce data there, for example "summarise the open opportunities on this account". Salesforce's security guidance is explicit: authorization code flow with PKCE only, no service accounts, no machine-to-machine flows, no autonomous operation outside a user context. Every call carries exactly the signed-in user's permissions, including field-level security and sharing rules.
That is good news for governance and a firm no for background agents. An agent that should prepare data at 3 a.m. belongs on the REST API.
Agentforce
Salesforce describes Agentforce as the agent-driven layer of its platform, with a Trust Layer between your data and the language model. Agents are built in Agentforce Builder or with Agent Script, and the Agent API lets outside systems chat with them over REST. Since April 2026, what used to be called topics are called subagents.
Agentforce makes sense when data and process sit mostly in Salesforce, the agent should work inside Salesforce's own interfaces, and you are happy not to bring your own model or infrastructure. Your own agent is the better fit when Salesforce is one source among several, when you want to choose the model or where it runs, or when the same logic must also work against other systems.
What do you need before you start?
You need admin access to Setup, a sandbox, a clear permission design and a good grasp of your data model. The effort usually sits less in the code than in permissions, field selection and clean test data.
- API allocation: REST calls count against the org's daily API allocation. The Limits resource at
/services/data/vXX.X/limits/reports it (entryDailyApiRequests); Salesforce says the figures are accurate within about five minutes and require the View Setup and Configuration permission. - Integration user: for client credentials, a dedicated user with a permission set that exposes only the objects and fields the agent needs. Never an admin account.
- Data model: which objects and fields does the agent genuinely need? Custom fields and objects (
__c) differ in every org, so the agent needs a plain description of what they mean. - Flex Credits for MCP: Salesforce says Hosted MCP Servers are intended only for customers with Flex Credits and usage may be billed.
- Data protection: customer data reaches a language model. Settle the data processing agreement, data location and which fields (notes, email bodies) should never be sent. Such an integration can be operated in line with the GDPR, but that comes from configuration and contracts, not from the technology; ask your privacy adviser when in doubt.
How should you roll it out?
Start with a read-only use case in a sandbox, measure answer quality against real questions, and widen permissions only after that. Write actions come last, and initially only with human approval.
- Pick one use case: for example, "meeting prep from the account, open opportunities and recent activities".
- Choose the route: per-user inside an AI client → Hosted MCP. Unattended, or many other systems involved → REST API. Mostly inside Salesforce with no need for your own model → evaluate Agentforce.
- Create the External Client App: in the sandbox, with minimal scopes. For MCP, add the client's callback URL; for REST, enable client credentials and assign the integration user.
- Design narrow tools: fixed, parameterised tools instead of free-form SOQL. On the MCP side Salesforce offers custom servers that bundle Apex invocable actions, Flows and Named Queries as tools.
- Test with real questions: collect twenty to thirty typical questions from the sales team and have the answers reviewed by people who know the accounts.
- Add write access gradually: first drafts (a task, a note) that a person confirms. Delete rights almost never.
- Run and monitor: watch API allocation, error rates and cost. Salesforce lets you filter MCP traffic in API logs with
API_CLIENT_CATEGORY = SALESFORCE_HOSTED_MCP.
What are the limits and risks?
The main risks are over-broad permissions, too many tools and misread data. On top come dependencies on Salesforce releases and consumption-based costs on the MCP side.
- Over-broad permissions: an integration user with "View All Data" turns every prompt injection attempt into a real threat. Keep access minimal and approve write actions one by one.
- Too many tools: Salesforce itself notes that AI clients struggle to pick the right tool once they see more than a few dozen. Small, task-specific servers or tool sets work better than
sobject-allfor everyone. - Data quality: an agent summarises what the CRM says. Stale stages, empty required fields or duplicate accounts produce confident but wrong answers.
- Release changes: Salesforce states that Hosted MCP servers, tools and prompts may change from release to release or be retired. Re-test after every release.
- Secrets: consumer secrets and tokens belong in a secrets store, never in code, prompts or logs.
- Cost: API allocation for REST, Flex Credits for MCP, plus model usage. Without monitoring, outliers show up only on the invoice.
In our own operations, starting every agent read-only with a short list of named tools has worked well; the problems that surface first are usually in the data model, not in the model.
How do you get started?
Begin with a sandbox, one External Client App and one read-only use case. If your team already uses an MCP-capable AI client, sobject-reads is the quickest test; for background jobs, start with one fixed SOQL query over the REST API.
After two or three weeks, write down which questions the agent answered well, where data was missing and which tools nobody used. That tells you whether to stay with MCP, move to your own agent on the REST API, or take a closer look at Agentforce. For examples of finished agents for sales, quotation and service work, see the pages on AI agents and the sales agent.
Frequently asked questions
Can I still create a Connected App for a new agent?
Only by asking Salesforce Support. Salesforce restricted Connected App creation as of Spring ’26; existing ones keep working, and External Client Apps are the recommended route for new integrations.
Can a scheduled job use the Hosted MCP Servers without anyone signing in?
No. Salesforce documents the authorization code flow with PKCE as the only supported flow, with no service accounts or machine-to-machine access. Scheduled jobs belong on the REST API with the client credentials flow.
Is MCP access billed separately?
Salesforce states that Hosted MCP Servers are intended only for customers with Flex Credits and that usage may be billed. Check this with your Salesforce account team before a pilot.
How many records does one SOQL query return through the REST API?
Up to 2,000 per synchronous response, sometimes fewer for large records. Follow nextRecordsUrl in the response to fetch the remaining batches.
Sources
- Salesforce REST API Developer Guide: Authorization Through External Client Apps or Connected Apps and OAuth 2.0 developer.salesforce.com
- Salesforce Developers: External Client Apps and Connected Apps developer.salesforce.com
- Salesforce Help: OAuth 2.0 Client Credentials Flow for Server-to-Server Integration help.salesforce.com
- Salesforce REST API Developer Guide: Query developer.salesforce.com
- Salesforce REST API Developer Guide: Execute a SOQL Query developer.salesforce.com
- Salesforce REST API Developer Guide: Limits developer.salesforce.com
- Salesforce Developers: Salesforce Hosted MCP Servers developer.salesforce.com
- Salesforce Hosted MCP Servers: Create an External Client App developer.salesforce.com
- Salesforce Hosted MCP Servers: Find Your Server URL developer.salesforce.com
- Salesforce Hosted MCP Servers: Security Best Practices developer.salesforce.com
- Salesforce Hosted MCP Servers: Standard MCP Servers Reference developer.salesforce.com
- Salesforce Hosted MCP Servers: Custom MCP Servers developer.salesforce.com
- Salesforce Hosted MCP Servers: End-of-Life developer.salesforce.com
- Salesforce Developers: Get Started with Agentforce and AI Agents developer.salesforce.com
- Salesforce Developers: Get Started with Agentforce APIs and SDKs developer.salesforce.com