From 46c010b6524fcdaa6874aa7fa138fc8dcb62d6ed Mon Sep 17 00:00:00 2001 From: Andrew Connor Date: Tue, 11 Aug 2026 20:55:05 -0400 Subject: [PATCH 1/6] docs: add Salesforce Hosted MCP Server setup guide [PLT-2845] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a provider-specific subpage under guides/mcp-gateways/add-remote-servers covering the Arcade-side OAuth2 configuration for connecting a Salesforce Hosted MCP Server, plus the handful of Salesforce External Client App settings (mcp_api scope, JWT-based access tokens, PKCE) that commonly cause a valid-looking setup to fail. Links out to Salesforce's own docs for creating and activating the server and the ECA rather than duplicating that content. This is the first provider-specific subpage under add-remote-servers, which is otherwise fully generic — see PLT-2845 for the open question of whether this pattern (and this content) belongs in the docs at all yet. Co-Authored-By: Claude Sonnet 5 --- .../mcp-gateways/add-remote-servers/_meta.tsx | 12 +++ .../mcp-gateways/add-remote-servers/page.mdx | 2 + .../add-remote-servers/salesforce/page.mdx | 101 ++++++++++++++++++ 3 files changed, 115 insertions(+) create mode 100644 app/en/guides/mcp-gateways/add-remote-servers/_meta.tsx create mode 100644 app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx diff --git a/app/en/guides/mcp-gateways/add-remote-servers/_meta.tsx b/app/en/guides/mcp-gateways/add-remote-servers/_meta.tsx new file mode 100644 index 000000000..f2511058b --- /dev/null +++ b/app/en/guides/mcp-gateways/add-remote-servers/_meta.tsx @@ -0,0 +1,12 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + index: { + title: "Overview", + }, + salesforce: { + title: "Salesforce", + }, +}; + +export default meta; diff --git a/app/en/guides/mcp-gateways/add-remote-servers/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/page.mdx index 12e28b8a6..0f4457c03 100644 --- a/app/en/guides/mcp-gateways/add-remote-servers/page.mdx +++ b/app/en/guides/mcp-gateways/add-remote-servers/page.mdx @@ -89,6 +89,8 @@ Common settings include: - **Custom headers**: Add headers such as `Authorization` or `X-API-Key` and reference secrets with `${secret:NAME}`. - **Header secrets**: Store API tokens or passwords and reference them in headers. +Some remote servers need provider-specific setup beyond these generic settings. See [Connect a Salesforce Remote MCP Server](/guides/mcp-gateways/add-remote-servers/salesforce) for a fully worked example. + ## Use remote tools in MCP Gateways Once the server is registered, its tools show up in the Playground for this project, as well as in the MCP Gateway tool picker. diff --git a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx new file mode 100644 index 000000000..22ae98497 --- /dev/null +++ b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx @@ -0,0 +1,101 @@ +--- +title: "Connect a Salesforce Hosted MCP Server" +description: "Configure a Salesforce External Client App and Arcade's OAuth 2.0 settings to connect a Salesforce Hosted MCP Server" +--- + +import { Callout, Steps } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + +# Connect a Salesforce Hosted MCP Server + +Salesforce can host an [MCP server](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/hosted-mcp-servers-overview.html) for an org, exposing tools such as SOQL queries directly from Salesforce data. This guide covers the Arcade-side setup for connecting a Salesforce Hosted MCP Server as a [remote MCP server](/guides/mcp-gateways/add-remote-servers), plus the handful of Salesforce settings that most commonly trip people up. + + + This guide is about connecting to a Salesforce Hosted MCP Server. If you're + looking to call Salesforce APIs from your own tools instead, see the + [Salesforce auth provider](/references/auth-providers/salesforce) guide. + + + + + +Connect a Salesforce Hosted MCP Server to Arcade and use its tools in gateways and SDKs. + + + + + +- An Arcade account +- A Salesforce [Hosted MCP Server](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/custom-servers.html), [activated](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/activate-mcp-servers.html) +- A Salesforce [External Client App](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/create-external-client-app.html) for the integration + + + + + +- Which Salesforce External Client App settings matter for Arcade specifically, and why +- Configure the remote server's OAuth 2.0 settings in Arcade +- Diagnose the most common setup mistakes from their error messages + + + + +## Set up Salesforce + +Follow Salesforce's own guides to [create your Hosted MCP Server](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/custom-servers.html), [activate it](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/activate-mcp-servers.html), and [create an External Client App](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/create-external-client-app.html) (ECA) for it. A few settings on the ECA matter specifically for connecting to Arcade: + +- **OAuth Scopes**: include `mcp_api`. Salesforce's guide lists this scope without explaining why it's required; without it, authorization succeeds, but every tool call fails with a 401. +- **Issue JSON Web Token (JWT)-based access tokens for named users** (under **Security**). Salesforce's guide instructs you to enable this without saying why. Without it, Salesforce issues an opaque session token instead of a JWT, and the Hosted MCP Server's endpoint only validates JWTs: every tool call fails with a bare `{"errors":[{"message":"Invalid token"}]}` 401, even though authorization otherwise looks successful. +- **Require PKCE**: Salesforce's ECA guide doesn't mention PKCE at all, but Arcade always uses it (RFC 7636, S256) when authorizing against a remote server. Leave PKCE enabled on the ECA (it's on by default). +- **Callback URL**: set this once you have the redirect URI Arcade generates (see [Add the redirect URI to your ECA](#add-the-redirect-uri-to-your-eca) below). You can use a placeholder now and come back to it. + +## Configure the remote server in Arcade + + + +### Register the server + +Go to the [MCP servers dashboard](https://api.arcade.dev/dashboard/servers), click **Add server**, and enter a server ID and the Hosted MCP Server's URL (it looks like `https://api.salesforce.com/platform/mcp/v1/custom/YourServerName`). + +### Configure OAuth2 authorization + +Open **Advanced settings → OAuth2 authorization** and enter: + +- **Client ID** / **Client Secret**: your ECA's Consumer Key and Consumer Secret. +- **Authorization URL**: your org's bare My Domain URL — for example, `https://your-org.my.salesforce.com`, or `https://your-org.develop.my.salesforce.com` for a Developer Edition org (find it under Salesforce Setup → **My Domain**). Enter the domain only, with no path. Arcade appends `/.well-known/openid-configuration` itself to discover the real authorization and token endpoints — so for a Developer Edition org, the value you enter should resolve at `https://your-org.develop.my.salesforce.com/.well-known/openid-configuration` (for example, `https://orgfarm-134f2f0dd4-dev-ed.develop.my.salesforce.com/.well-known/openid-configuration`). Don't use the ECA's `/authorize` path or `api.salesforce.com` — neither serves that discovery document. + + + Salesforce Hosted MCP Servers don't support Dynamic Client Registration, so + you must supply the Client ID and Secret manually. If you leave these + blank, Arcade attempts Dynamic Client Registration and Salesforce rejects + it. + + +### Add the redirect URI to your ECA + +Copy the redirect URI Arcade generated and set it as the ECA's Callback URL. A new server registration gets its own unique redirect URI, so update the Callback URL again if you ever re-register the server under a new ID. + +### Authorize and confirm + +Save the server and complete the authorization prompt. On the scope selection screen, confirm `mcp_api` is checked — Arcade lists every scope your org's discovery document advertises as supported, not just the ones your ECA actually grants, so only select scopes your ECA has enabled. + + + + + Don't refresh the Arcade dashboard while an authorization prompt is open. + Refreshing mid-flow can leave a stale, incomplete authorization behind + instead of cleanly restarting it. If a connection seems stuck, close the + prompt, reload the page, and start a single fresh attempt. + + +## Troubleshooting + +- **A 401 with `{"errors":[{"message":"Invalid token"}]}` and no error code**: your ECA isn't issuing JWT-based access tokens. See [Set up Salesforce](#set-up-salesforce). +- **Authorization succeeds, but tool calls 401**: the `mcp_api` scope is missing from either the ECA's Selected Scopes or the scopes you approved during authorization. +- **Tools list is empty or every call fails**: confirm the Hosted MCP Server is [activated](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/activate-mcp-servers.html). +- **A setting change doesn't seem to take effect**: existing tokens don't retroactively pick up new ECA settings. In Salesforce Setup, go to the affected user's **OAuth Apps** list and revoke the existing grant, then re-authorize to get a fresh token. + +## Next steps + +- [Create an MCP Gateway](/guides/mcp-gateways/create-via-dashboard) to expose this server's tools. +- [Connect to MCP clients](/get-started/mcp-clients). From 0bfcc6ec4980a74b540fdd10fdee07bc4156bd32 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 12 Aug 2026 00:55:57 +0000 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=A4=96=20Regenerate=20LLMs.txt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- public/llms.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/public/llms.txt b/public/llms.txt index 1554ae69a..6f0c2f46c 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,4 +1,4 @@ - + # Arcade @@ -97,6 +97,7 @@ Arcade delivers three capabilities. Enforce (Agent Authorization): deploy agents - [Clerk](https://docs.arcade.dev/en/guides/user-sources/clerk): Documentation page - [Comparative evaluations](https://docs.arcade.dev/en/guides/create-tools/evaluate-tools/comparative-evaluations): The "Comparative Evaluations" documentation page provides users with the tools and guidance to compare different AI model implementations using isolated tool registries, known as tracks. It outlines how to set up and conduct evaluations to assess tool selection and performance across various contexts - [Compare MCP Server Types](https://docs.arcade.dev/en/guides/create-tools/tool-basics/compare-server-types): This documentation page provides a comparative overview of different MCP server types, detailing their functionalities based on transport methods and deployment options. Users can learn about the capabilities of each server type, including support for various tools and authentication methods, to help them choose the most +- [Connect a Salesforce Hosted MCP Server](https://docs.arcade.dev/en/guides/mcp-gateways/add-remote-servers/salesforce): Documentation page - [Connect Arcade to your LLM](https://docs.arcade.dev/en/get-started/agent-frameworks/setup-arcade-with-your-llm-python): This documentation page guides users on how to connect Arcade to a Large Language Model (LLM) using Python by creating a "harness" that facilitates interaction between the user, the model, and various tools. Users will learn to set up an agent - [Connect to MCP Clients](https://docs.arcade.dev/en/get-started/mcp-clients): This documentation page provides guidance on connecting Arcade MCP servers to various MCP-compatible clients and development environments, enabling users to enhance their agent workflows. - [Contact Us](https://docs.arcade.dev/en/resources/contact-us): This documentation page provides users with information on how to connect with the Arcade team for support through various channels. It aims to facilitate communication and assistance for users and their agents. From dd96cd4ed04c7adb0808b26b7e02556102c174a0 Mon Sep 17 00:00:00 2001 From: Andrew Connor Date: Tue, 11 Aug 2026 21:23:24 -0400 Subject: [PATCH 3/6] docs: fix Authorization URL guidance for Salesforce Hosted MCP Server MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The field needs the full well-known OpenID configuration URL, not the bare My Domain root as previously written — confirmed against the actual dashboard field. --- .../guides/mcp-gateways/add-remote-servers/salesforce/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx index 22ae98497..8d2f717a1 100644 --- a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx +++ b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx @@ -62,7 +62,7 @@ Go to the [MCP servers dashboard](https://api.arcade.dev/dashboard/servers), cli Open **Advanced settings → OAuth2 authorization** and enter: - **Client ID** / **Client Secret**: your ECA's Consumer Key and Consumer Secret. -- **Authorization URL**: your org's bare My Domain URL — for example, `https://your-org.my.salesforce.com`, or `https://your-org.develop.my.salesforce.com` for a Developer Edition org (find it under Salesforce Setup → **My Domain**). Enter the domain only, with no path. Arcade appends `/.well-known/openid-configuration` itself to discover the real authorization and token endpoints — so for a Developer Edition org, the value you enter should resolve at `https://your-org.develop.my.salesforce.com/.well-known/openid-configuration` (for example, `https://orgfarm-134f2f0dd4-dev-ed.develop.my.salesforce.com/.well-known/openid-configuration`). Don't use the ECA's `/authorize` path or `api.salesforce.com` — neither serves that discovery document. +- **Authorization URL**: the full OpenID Connect discovery URL for your org, not just the bare domain: take your org's My Domain URL (find it under Salesforce Setup → **My Domain**) and append `/.well-known/openid-configuration`. For example, `https://your-org.my.salesforce.com/.well-known/openid-configuration`, or `https://your-org.develop.my.salesforce.com/.well-known/openid-configuration` for a Developer Edition org (concretely, something like `https://orgfarm-134f2f0dd4-dev-ed.develop.my.salesforce.com/.well-known/openid-configuration`). Arcade fetches this URL to discover the real authorization and token endpoints. Don't use the ECA's `/authorize` path or `api.salesforce.com`: neither serves that discovery document. Salesforce Hosted MCP Servers don't support Dynamic Client Registration, so From 44a3a950e30760466be0270a8b658ce3c72edb4a Mon Sep 17 00:00:00 2001 From: Andrew Connor Date: Tue, 11 Aug 2026 21:25:18 -0400 Subject: [PATCH 4/6] docs: use a generic production-style example domain instead of our dev org --- .../guides/mcp-gateways/add-remote-servers/salesforce/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx index 8d2f717a1..3fe2476e8 100644 --- a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx +++ b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx @@ -62,7 +62,7 @@ Go to the [MCP servers dashboard](https://api.arcade.dev/dashboard/servers), cli Open **Advanced settings → OAuth2 authorization** and enter: - **Client ID** / **Client Secret**: your ECA's Consumer Key and Consumer Secret. -- **Authorization URL**: the full OpenID Connect discovery URL for your org, not just the bare domain: take your org's My Domain URL (find it under Salesforce Setup → **My Domain**) and append `/.well-known/openid-configuration`. For example, `https://your-org.my.salesforce.com/.well-known/openid-configuration`, or `https://your-org.develop.my.salesforce.com/.well-known/openid-configuration` for a Developer Edition org (concretely, something like `https://orgfarm-134f2f0dd4-dev-ed.develop.my.salesforce.com/.well-known/openid-configuration`). Arcade fetches this URL to discover the real authorization and token endpoints. Don't use the ECA's `/authorize` path or `api.salesforce.com`: neither serves that discovery document. +- **Authorization URL**: the full OpenID Connect discovery URL for your org, not just the bare domain: take your org's My Domain URL (find it under Salesforce Setup → **My Domain**) and append `/.well-known/openid-configuration`. For example, `https://mycompany.my.salesforce.com/.well-known/openid-configuration`. Arcade fetches this URL to discover the real authorization and token endpoints. Don't use the ECA's `/authorize` path or `api.salesforce.com`: neither serves that discovery document. Salesforce Hosted MCP Servers don't support Dynamic Client Registration, so From 596336c76746b730ee1da598a8c3ce9a2fe1e917 Mon Sep 17 00:00:00 2001 From: Andrew Connor Date: Tue, 11 Aug 2026 21:26:43 -0400 Subject: [PATCH 5/6] docs: match acme-inc example convention from the Salesforce auth-provider page --- .../guides/mcp-gateways/add-remote-servers/salesforce/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx index 3fe2476e8..95c6af973 100644 --- a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx +++ b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx @@ -62,7 +62,7 @@ Go to the [MCP servers dashboard](https://api.arcade.dev/dashboard/servers), cli Open **Advanced settings → OAuth2 authorization** and enter: - **Client ID** / **Client Secret**: your ECA's Consumer Key and Consumer Secret. -- **Authorization URL**: the full OpenID Connect discovery URL for your org, not just the bare domain: take your org's My Domain URL (find it under Salesforce Setup → **My Domain**) and append `/.well-known/openid-configuration`. For example, `https://mycompany.my.salesforce.com/.well-known/openid-configuration`. Arcade fetches this URL to discover the real authorization and token endpoints. Don't use the ECA's `/authorize` path or `api.salesforce.com`: neither serves that discovery document. +- **Authorization URL**: the full OpenID Connect discovery URL for your org, not just the bare domain: take your org's My Domain URL (find it under Salesforce Setup → **My Domain**) and append `/.well-known/openid-configuration`. For example, `https://acme-inc.my.salesforce.com/.well-known/openid-configuration`. Arcade fetches this URL to discover the real authorization and token endpoints. Don't use the ECA's `/authorize` path or `api.salesforce.com`: neither serves that discovery document. Salesforce Hosted MCP Servers don't support Dynamic Client Registration, so From a66c89dc186307d10144c48ceab8d3283eb5625b Mon Sep 17 00:00:00 2001 From: Andrew Connor Date: Wed, 12 Aug 2026 06:58:53 -0400 Subject: [PATCH 6/6] docs: address review nits, add scope-picker warning for Salesforce guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Link to the Arcade Salesforce toolkit instead of the auth-provider page when a reader wants to call Salesforce APIs from their own tools (Evan). - Move the "don't refresh mid-flow" warning to the generic add-remote-servers guide — it's Arcade dashboard behavior, not Salesforce-specific (Evan). - Add an explicit warning that the authorization prompt's scope picker lists every scope the org's discovery document supports, not just what the ECA grants, and that leaving an unmatched scope selected fails authorization outright (not just later tool calls). --- .../mcp-gateways/add-remote-servers/page.mdx | 7 ++++++ .../add-remote-servers/salesforce/page.mdx | 24 ++++++++++++------- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/app/en/guides/mcp-gateways/add-remote-servers/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/page.mdx index 0f4457c03..bb3f900b1 100644 --- a/app/en/guides/mcp-gateways/add-remote-servers/page.mdx +++ b/app/en/guides/mcp-gateways/add-remote-servers/page.mdx @@ -76,6 +76,13 @@ Create the server and confirm that Arcade lists the server tools in your project Arcade pre-loads the list of tools available to the user who configures the remote MCP server so that you can filter them by your own criteria in your MCP Gateways. Be sure to connect as an 'admin' user who has access to the broadest selection of tools in the remote server. Arcade then re-load the list of tools for every user using your agent - if a tool is not available to the agent's end-user, it will not be available via the gateway. + + Don't refresh the Arcade dashboard while an authorization prompt is open. + Refreshing mid-flow can leave a stale, incomplete authorization behind + instead of cleanly restarting it. If a connection seems stuck, close the + prompt, reload the page, and start a single fresh attempt. + + ## Configure advanced settings diff --git a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx index 95c6af973..8c7bfa7d5 100644 --- a/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx +++ b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx @@ -13,7 +13,7 @@ Salesforce can host an [MCP server](https://developer.salesforce.com/docs/platfo This guide is about connecting to a Salesforce Hosted MCP Server. If you're looking to call Salesforce APIs from your own tools instead, see the - [Salesforce auth provider](/references/auth-providers/salesforce) guide. + [Arcade Salesforce toolkit](/resources/integrations/sales/salesforce). @@ -77,20 +77,28 @@ Copy the redirect URI Arcade generated and set it as the ECA's Callback URL. A n ### Authorize and confirm -Save the server and complete the authorization prompt. On the scope selection screen, confirm `mcp_api` is checked — Arcade lists every scope your org's discovery document advertises as supported, not just the ones your ECA actually grants, so only select scopes your ECA has enabled. - - +Save the server to open the authorization prompt. - Don't refresh the Arcade dashboard while an authorization prompt is open. - Refreshing mid-flow can leave a stale, incomplete authorization behind - instead of cleanly restarting it. If a connection seems stuck, close the - prompt, reload the page, and start a single fresh attempt. + The scope picker on this screen lists every scope your org's My Domain + discovery document advertises as supported — Salesforce orgs typically + support dozens (`api`, `chatbot_api`, `cdp_api`, `lightning`, and so on), + regardless of what your ECA actually grants. **Deselect every scope except + the ones your ECA's Selected Scopes includes** (per [Set up + Salesforce](#set-up-salesforce) above — at minimum `mcp_api`, plus whichever + of `api`, `offline_access`, and `refresh_token` your ECA grants). Leaving an + extra scope checked makes the authorization request fail, not just the + later tool calls. +Complete the authorization prompt. + + + ## Troubleshooting - **A 401 with `{"errors":[{"message":"Invalid token"}]}` and no error code**: your ECA isn't issuing JWT-based access tokens. See [Set up Salesforce](#set-up-salesforce). +- **Authorization fails outright**: a scope was selected on the authorization prompt that your ECA doesn't actually grant. See [Authorize and confirm](#authorize-and-confirm). - **Authorization succeeds, but tool calls 401**: the `mcp_api` scope is missing from either the ECA's Selected Scopes or the scopes you approved during authorization. - **Tools list is empty or every call fails**: confirm the Hosted MCP Server is [activated](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/activate-mcp-servers.html). - **A setting change doesn't seem to take effect**: existing tokens don't retroactively pick up new ECA settings. In Salesforce Setup, go to the affected user's **OAuth Apps** list and revoke the existing grant, then re-authorize to get a fresh token.