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..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 @@ -89,6 +96,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..8c7bfa7d5 --- /dev/null +++ b/app/en/guides/mcp-gateways/add-remote-servers/salesforce/page.mdx @@ -0,0 +1,109 @@ +--- +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 + [Arcade Salesforce toolkit](/resources/integrations/sales/salesforce). + + + + + +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**: 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 + 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 to open the authorization prompt. + + + 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. + +## 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). 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.