MeshMesh
Guides

Connecting Salesforce Headless 360 (Read-Only)

Give agents read-only access to a Salesforce org through Salesforce's hosted Headless 360 MCP — a good fit for analyzing production orgs

Beta

Salesforce Headless 360 is in beta and available on request. Contact your MeshMesh team to turn it on for your workspace. On Salesforce's side, the Headless 360 MCP Server is also a Beta Service, subject to Salesforce's Beta Services Terms.

Salesforce Headless 360 (Read-Only) connects MeshMesh to Salesforce's hosted Headless 360 MCP server. Agents can explore and query an org's data and metadata, but they can't change anything. That makes it a good fit for analyzing production orgs.

What agents can and can't do

Agents work through Salesforce's library of Headless 360 operations, finding the right one at runtime. Salesforce is growing that library with each release; at beta launch it focuses mainly on Setup tasks for admins, so what agents can read depends on the operations Salesforce currently offers.

Agents can:

  • Discover what the org offers (discover).
  • Describe objects and fields (describe).
  • Read data and metadata with read-only requests (dispatch_readonly: GET requests to read endpoints such as queries, searches, record and object reads, UI API and limits).

Agents can't:

  • Create, update or delete records, or change settings.
  • Run Apex, or call Apex REST or Visualforce endpoints.
  • Download file bodies.

Headless 360 or a regular Salesforce connection?

Use Headless 360 when agents only need to read and analyze. Use a regular Salesforce connection when agents need to build, deploy or change data.

Before you start

You need:

  • A Salesforce user with System Administrator (or equivalent) permissions, to activate the server and create the External Client App.
  • An org on Salesforce API version 67.0 or later, where the Headless 360 MCP Server is available.
  • For production orgs, a read-only Salesforce user to connect with (see step 4).

Set up

Activate the Headless 360 MCP server

In Salesforce Setup, go to Integrations → API Catalog, open Headless360 (H360) MCP Server, and click Activate. Activation can take a couple of minutes.

Create an External Client App

In Setup → External Client App Manager, choose New External Client App and turn on OAuth. Then set:

  • Callback URLs — add the URL for each MeshMesh app you use. If you use both, add both:

    Where you use MeshMeshCallback URL
    Web apphttps://studio.meshmesh.io/auth/sf-callback
    Desktop apphttps://auth.meshmesh.io/sf-callback

    The MeshMesh connection dialog shows the same URLs with copy buttons. Salesforce rejects a URL with a trailing space.

  • OAuth scopes — exactly these two:

    • mcp_api
    • refresh_token

    MeshMesh refuses a connection that grants broader scopes, such as api or full.

  • Require PKCE — on.

  • Issue JWT-based access tokens for named users — on. Headless 360 requires JWT-based tokens.

  • Refresh token policy — we recommend refresh-token rotation and expiring refresh tokens after a period of inactivity (for example, 30 days).

  • Consumer secret — optional. MeshMesh connects as a PKCE client, so you only need to provide the secret if your app requires one.

Copy the Consumer Key

Open the app's Settings → OAuth Settings → Consumer Key and Secret and copy the Consumer Key. Salesforce first emails you a verification code; enter it to reveal the key.

A new External Client App can take up to 30 minutes to start working. If connecting fails right after you create it, wait and try again.

Choose the Salesforce user to connect with

Agents act as the Salesforce user who connects. They can read everything that user can read.

  • For production orgs, use a dedicated read-only integration user. Give it a read-only permission set without Modify All Data, Customize Application, Author Apex or Manage Users. MeshMesh keeps the connection read-only either way; a read-only user makes Salesforce enforce it too.
  • Grant only the objects and fields agents should see. Avoid users who can read sensitive data, such as login history, setup audit trail or custom settings that hold credentials, unless agents need it.
  • Optionally, require a permission set to pre-authorize the app, so only approved users can connect it.

If the connected user has admin-level permissions, MeshMesh shows a reminder in the connection's settings. Your workspace can also require read-only users for production orgs. Ask your MeshMesh team to turn this on.

Connect in MeshMesh

  1. Open Integrations → Salesforce Headless 360 (Read-Only).
  2. Paste the Consumer Key, and the Consumer Secret only if your app requires one.
  3. Choose the environment: Production, Sandbox, or My Domain (enter your *.my.salesforce.com host).
  4. Select Connect with Salesforce, sign in as the user from the previous step, and approve access.

Use it with agents

Attach Salesforce Headless 360 to an agent when you start it, or add it to a running agent from the chat's integrations menu. Then ask in plain language, for example: "Summarize our open opportunities by stage" or "Which custom objects have the most records?"

If an agent says Headless 360 isn't available in its session, start a new agent. Some older sessions can't use it.

How MeshMesh keeps it read-only and secure

Every Headless 360 request runs as the Salesforce user who connected. Salesforce applies that user's object permissions, field-level security, sharing rules and permission sets, and records each action under that user in its audit trail. On top of that:

  • The Salesforce token stays with MeshMesh. It never enters the agent's workspace. Agents reach Headless 360 only through MeshMesh, which refreshes the token for you.
  • Read-only is enforced by MeshMesh, on every request, whatever the agent asks for. Write tools are hidden and refused.
  • Only you can use your connection. Other people in your workspace can't attach it to their agents, and access is tied to the agent and its workspace.
  • Stopping an agent cuts its access right away.
  • Every request is logged for audit.

Troubleshooting

"Salesforce did not grant the mcp_api scope" — Add mcp_api to the External Client App's OAuth scopes, turn on Issue JWT-based access tokens for named users, then reconnect.

"Salesforce granted more than the mcp_api and refresh_token scopes" — The app grants broader scopes. Set its OAuth scopes to exactly mcp_api and refresh_token, then connect again from MeshMesh.

"redirect_uri mismatch" / invalid redirect URI — Add the exact callback URL for the app you're using (web or desktop) to the External Client App, with no trailing space.

Unknown or invalid Consumer Key — Check that you copied the Consumer Key, not the secret. A new app can take up to 30 minutes to start working.

Sign-in goes to the wrong org — Choose the environment that matches the org: Sandbox for sandboxes, My Domain for a custom domain, Production otherwise.

Connection needs to be reconnected — The refresh token expired, usually after a long period of inactivity. Select Reconnect on the connection.

Agents can't use the connection in a production org — If your workspace requires read-only users for production orgs, reconnect with a user that doesn't have admin-level permissions.

Connecting a Salesforce Org

Choose how to connect a Salesforce org to MeshMesh — read-only for production, read-write for sandboxes and developer orgs

Connecting Marketing Cloud Engagement

Set up Salesforce Marketing Cloud Engagement as an integration in MeshMesh

On this page

What agents can and can't doBefore you startSet upActivate the Headless 360 MCP serverCreate an External Client AppCopy the Consumer KeyChoose the Salesforce user to connect withConnect in MeshMeshUse it with agentsHow MeshMesh keeps it read-only and secureTroubleshooting