Salesforce

Overview

This guide explains how to connect Salesforce to Forge using the Salesforce-hosted MCP server (Hosted MCP). It is intended for Salesforce administrators and Forge workspace administrators.

The Salesforce integration in Forge relies on two configuration levels:

Once connected, the Forge coach can query your CRM data (accounts, opportunities, contacts, etc.) within the scope of the signed-in user's permissions.

Important: the data visible to the coach is limited to what the connected Salesforce user can access. Forge does not bypass Salesforce permissions.

Prerequisites

On the Salesforce side

• Administrator access (or equivalent) to your Salesforce org (production or sandbox).
• The ability to create an External Client App with OAuth 2.0.
• Hosted MCP Servers enabled for your org (a Salesforce feature — see the official documentation).
• Your My Domain URL in the format https://…my.salesforce.com.

On the Forge side

• Administrator role on the relevant Forge workspace.
• Access to Settings → Integrations → Tools (or Settings → Tools).

Step 0 — Activate Hosted MCP Servers in Salesforce

Salesforce administrator. Do this first — if the MCP servers are not activated, the connection from Forge will not work, no matter how well the rest is configured.

1. In Salesforce, open Setup > Integrations > API Catalog > MCP Servers.
2. Open the SObject Reads server (platform/sobject-reads, read-only access to SObjects) — this is the server Forge uses.
3. Click Activate. MCP servers are inactive by default.
4. Allow up to 2 minutes for a server to become active after you enable it.

Once the servers are active, continue with Step 1. See the Salesforce guide on activating MCP servers for details.

Step 1 — Create an External Client App in Salesforce

The exact labels in Setup may vary depending on your Salesforce version. For up-to-date details, see the Salesforce documentation on Hosted MCP Servers.

1.1 Create the app

1. Sign in to Salesforce as an administrator.
2. Open Setup > External Client App Manager and click New External Client App.
3. Basic Information section: enter a name (e.g. Forge), a contact email, and set Distribution State = Local.

1.2 Configure OAuth

1. Expand the API (Enable OAuth Settings) section and check Enable OAuth.
2. In Callback URL, paste the URL copied from Forge (see the "Callback URL" section below).
3. OAuth Scopes: move exactly these two scopes to the selected scopes list:
   • Access Salesforce hosted MCP servers (mcp_api)
   • Perform requests at any time (refresh_token, offline_access)

1.3 Security settings

In the Security section:

• Check Issue JSON Web Token (JWT)-based access tokens for named users. This box is unchecked by default and it is required.
• Leave Require secret for Web Server Flow and Require secret for Refresh Token Flow unchecked. If either is checked, the OAuth connection from Forge will fail.
• Leave all Flow Enablement options unchecked.
• PKCE, refresh token rotation and the 30-day inactivity limit are already checked and locked by Salesforce: nothing to do.

Then click Create.

Forge uses OAuth 2.0 with PKCE: a Consumer Secret is not needed (the flow works with the Consumer Key / Client ID only).

1.4 Get the Consumer Key

1. In the new app, open the Settings tab.
2. Expand OAuth Settings and click the Consumer Key and Secret button.
3. Copy only the Consumer Key — the secret is not needed.

Note: a brand-new app can take a few minutes before Salesforce accepts connections.

Your org URL (My Domain)

Forge accepts any URL from your org: it automatically converts it to your My Domain URL and shows it below the field ("Forge will use: https://…"). Accepted:

• a Lightning URL (….lightning.force.com);
• a Setup page URL (….my.salesforce-setup.com);
• the My Domain URL (….my.salesforce.com);
• an http:// URL (converted to https://);
• or simply the org name.

Examples: production https://your-company.my.salesforce.com; sandbox your-org--uat.sandbox.my.salesforce.com.

Only the generic login.salesforce.com and test.salesforce.com URLs are rejected, with their own error message.

Callback URL

The OAuth callback URL must be registered identically in Salesforce and follows this format:

{FORGE_API_URL}/tools-oauth/salesforce-mcp/callback

Examples by Forge environment

Recommendation: copy the URL shown in Forge during Organization setup — that is the exact value to paste into Salesforce. Do not change the path, the case, or trailing slashes.

Step 2 — Organization setup in Forge

Workspace administrator only.

1. Open Settings → Integrations → Tools.
2. On the Salesforce card, click Org config required.
3. The panel shows a step-by-step guide with the callback URL to copy: add it to your Salesforce External Client App (Step 1).
4. Fill in:
   • Instance URL — your Salesforce org URL (see "Your org URL" above)
   • Consumer key / Client ID — the Consumer Key from your External Client App
5. Click Test connection. Before you save, Forge checks:
   • that the Salesforce org exists;
   • that the consumer key is recognized;
   • that the callback URL is registered in the app.
   Each check is shown with a status and, if it fails, the fix to apply.
6. Save.

The OAuth scopes, the JWT setting and MCP server activation can only be verified when a member connects.

If the test reports that the key is not recognized right after creating the app, wait a few minutes and run the test again.

This step does not yet connect a user: it prepares the workspace so each member can connect individually.

Step 3 — User connection

For every Forge user who wants to use Salesforce with the coach.

1. Open Settings → Integrations → Tools.
2. Click Salesforce → Connect (or edit an existing connection).
3. Name the connection if needed (e.g. "Salesforce — John").
4. Click Connect: you will be redirected to Salesforce to authorize access.
5. Accept the requested permissions.
6. Once redirected back, the connection appears as active in Forge.

Each user must complete this step with their own Salesforce account.

What the coach can do

Forge connects to the Salesforce-hosted MCP server platform/sobject-reads (read-only access to authorized SObjects).

In particular, the coach can help you:

• Find accounts, contacts, opportunities and leads
• Prepare sales meetings and follow-ups
• Track your pipeline within the scope of your Salesforce permissions

Forge signals (open opportunities, recently lost deals) are also computed from the connected user's data.

Removing the connection

1. Go to Settings > Tools.
2. Find the Salesforce connection and click Remove (trash icon).
3. Confirm in the confirmation dialog.

Implications of removal:

• The coach immediately loses access to Salesforce data and can no longer query it during conversations.
• Salesforce-related signals (open opportunities, recently lost deals) will no longer be generated.
• Ongoing conversations are not interrupted, but any request involving Salesforce will be reported as unavailable.
• Data: Forge stores no Salesforce data permanently — the integration is real-time and no copy is retained after removal. The OAuth authorization is revoked on the Forge side; you can also revoke it in Salesforce (Setup > External Client Apps > OAuth Usage).
• You can reconnect Salesforce at any time by repeating step 3.

Sandbox vs production

Configure one External Client App per org (sandbox and production are separate). If you test in a sandbox first, redo the organization setup in Forge with the sandbox URL and Consumer Key.

Troubleshooting

"instanceUrl must be your Salesforce org URL…"

• This message only appears if the URL entered is not a Salesforce URL.
• If you pasted login.salesforce.com or test.salesforce.com, use your own org's URL instead.

OAuth error / "redirect_uri mismatch"

• The callback URL in Salesforce must match exactly the one shown in Forge.
• Check for stray spaces, extra slashes, or an http / https mismatch.

PKCE / scopes rejected

• Both scopes Access Salesforce hosted MCP servers (mcp_api) and Perform requests at any time (refresh_token, offline_access) must be selected.
• The options Require secret for Web Server Flow and Require secret for Refresh Token Flow must be unchecked (PKCE does not use a Consumer Secret).

The coach sees no data

• Are the Hosted MCP servers activated in Salesforce (Step 0)?
• Has the Forge user connected their own Salesforce account?
• Has the administrator completed the organization setup?
• Does the Salesforce user have read access to the relevant objects (Opportunity, Account, etc.)?

Expired connection

• Forge attempts to refresh the token automatically via refresh_token.
• If the coach suddenly no longer sees Salesforce data (app deleted or changed, MCP server deactivated, access revoked, 30 days without use), remove the Salesforce connection in Forge and reconnect.

Members can't connect

• Only a workspace administrator can perform the organization setup.
• Until that step is done, users will see a message indicating that the workspace configuration is pending.

Messages shown when a member connects

Forge identifies the following cases and tells you how to fix them:

• Salesforce asked for a secret → uncheck both Require secret… boxes (Step 1.3).
• Token not usable by the MCP server → check Issue JSON Web Token (JWT)-based access tokens for named users (Step 1.3).
• MCP server inactive → activate SObject Reads in Setup > Integrations > API Catalog > MCP Servers (Step 0).
• Connection refused by the MCP server → add the Access Salesforce hosted MCP servers (mcp_api) scope (Step 1.2).

In each case, once fixed, the member reconnects.

Summary checklist

Salesforce administrator

• SObject Reads MCP server (platform/sobject-reads) activated
• External Client App created (Distribution State = Local)
• Enable OAuth checked and Forge callback URL registered
• Scopes "Access Salesforce hosted MCP servers (mcp_api)" + "Perform requests at any time (refresh_token, offline_access)" selected
• "Issue JSON Web Token (JWT)-based access tokens for named users" checked
• "Require secret for Web Server Flow" and "Require secret for Refresh Token Flow" unchecked
• All Flow Enablement options unchecked (PKCE: already enabled by default)
• Consumer Key noted
• Org URL identified

Forge workspace administrator

• Organization setup saved (Instance URL + Consumer key)
• Callback URL verified
• Test connection successful in Forge

End user

• Personal Salesforce connection created in Forge
• OAuth authorization accepted in Salesforce

Resources

• Salesforce documentation — Hosted MCP Servers
• Salesforce — Activate MCP Servers
• Salesforce — External Client Apps (Salesforce Setup labels)

Support

For any question about Forge configuration, contact your usual Forge representative or support through the app.

For questions about Salesforce permissions, External Client Apps, or enabling MCP in your org, contact your Salesforce administrator.