Read live Salesforce data through MCP

Overview

The copilot has two places it can read from, and it always tells you which one it used:

• Indexed metadata (the default) — a snapshot from the org's last sync plus your uploaded documents and verified learnings. Fast, no call to the org, no API budget spent, and every answer states the index date. Everything about Apex, flows, permission sets, dependencies and documents comes from here.
• Live org data — the org as it is right now, read at answer time through a connector: a Salesforce hosted MCP server, any other MCP server that speaks Streamable HTTP, or — for a plain SOQL question — the org's own connection. Record questions live here: how many active users right now, which deals stalled this quarter, the ten most recently modified accounts. Every live call is written to the audit log, is read-only unless a curator allows writes, and even then each write waits for an approval in the chat.

In the copilot's header strip an Indexed · Live · Auto toggle says where answers may come from:

A live answer carries a teal Live chip and [V1]-style evidence that reads Live from acme-prod via mcp (Production MCP) at 2026-10-26T09:14:02Z, so a figure from the org is never mistaken for a figure from the index. When an answer mixes both — for example a live user count beside the last Access 360 scan's count — the chip says so and the evidence list names which is which.

The Live data tab of Org Knowledge is where connectors are added, tested and controlled.

Before you start

• Permissions. Manage live data connectors (live.manage) adds, edits, tests and removes connectors and is the permission that approves an action that can change data; Admin, Architect and DevOps have it by default. Query live org data (live.query) lets the copilot read live records on your behalf; every role except Viewer has it by default. Reading the Live data tab needs neither. See Roles and permissions.
• A connected org. The org must already be connected under Connections — see Connect a Salesforce org. If its credential still refreshes, the copilot can already run read-only SOQL against it through the org's own connection, with no MCP server at all.
• For a Salesforce hosted MCP server, per Salesforce documentation: the org must be Enterprise Edition or above, or a Developer Edition org; the MCP Service must be enabled in Setup; the server you want (for reads, platform/sobject-reads) must be activated — all servers are off until an admin activates them; and you need an External Client App with OAuth enabled, the scopes Access Salesforce hosted MCP servers (mcp_api) and refresh_token, PKCE required and JSON Web Token (JWT)-based access tokens issued. Legacy Connected Apps and the older beta scopes are not accepted, and a newly created External Client App can take up to 30 minutes to work everywhere. Government Cloud availability should be confirmed with Salesforce first.
• Know what the server accepts. Per Salesforce documentation, the hosted servers accept only a token issued by a person signing in through the External Client App (authorization code with PKCE); service-account, client-credentials and machine-to-machine flows are not supported, and an org's ordinary connection token is refused. That is why a Salesforce connector in MetaLens360 uses Sign in with Salesforce: one person signs in once, MetaLens360 keeps the refresh token encrypted and renews the access token itself, and every live call then runs as that person with their permissions and sharing. The other authentication modes exist for generic MCP servers. MetaLens360's test tells you plainly when a server refuses the credential.
• The External Client App's callback URL must be your MetaLens360 site followed by /api/v1/live/oauth/callback — for example https://metalens360.com/api/v1/live/oauth/callback. The Live data tab shows the exact value for your site. Your platform admin may register one app for the whole MetaLens360 server (its consumer key is configured there) so individual connectors need no key at all; a connector can also carry its own consumer key and secret.
• Treat tool descriptions and tool results from any MCP server as data, not instructions: the copilot is told never to follow text found inside them.

Steps

Prepare the org in Salesforce

These steps happen in Salesforce Setup and are described here only as far as the connector needs them; follow Salesforce's own documentation for the screens.

1. Turn on Enable MCP Service in Setup.
2. Open MCP Servers (under the API Catalog), choose Salesforce Servers, open the server you want — platform/sobject-reads for read-only record access — and Activate it. Activation can take a couple of minutes; a server that is not active answers with not found.
3. In External Client App Manager, create an app with OAuth enabled and:
   • Callback URL: your MetaLens360 site followed by /api/v1/live/oauth/callback (shown on the Live data tab);
   • OAuth scopes: Access Salesforce hosted MCP servers (mcp_api) and Perform requests at any time (refresh_token);
   • Security: Require Proof Key for Code Exchange (PKCE) and Issue JSON Web Token (JWT)-based access tokens for named users ticked; Require Secret for Web Server Flow and Require Secret for Refresh Token Flow are optional (if you tick them, enter the consumer secret in MetaLens360 too); every other flow off. Copy the consumer key, and the consumer secret if you require one. Give the app up to 30 minutes to propagate before the first sign-in.
4. Decide who may use it: by default any user can self-authorise; to restrict it, set permitted users to admin approved and attach a permission set or profile. The person who signs in from MetaLens360 must be allowed here, and every live call runs with that person's object permissions, field security and sharing.
5. You do not need to copy the endpoint: MetaLens360 builds it from the org's My Domain and type when you pick the server. For reference it is on the shared Salesforce API host (api.salesforce.com), then /platform/mcp/v1/d/, your My Domain name, then the server name; sandboxes add a sandbox segment after the My Domain name, Developer Edition orgs develop, scratch orgs scratch. The endpoint is not on your My Domain host.

Add the connector in MetaLens360

1. Open Org Knowledge from the left navigation (under Overview), choose the org in the Org picker and open the Live data tab. The two cards at the top show Indexed metadata and Live via MCP, and a chip says whether live data is currently available for that org and why not.
2. Click Add connector.
3. Fill in a Name (for example Production — Salesforce MCP), choose Kind = Salesforce and the Org it belongs to. A Salesforce connector must be bound to one org, and it is never used for another.
4. Pick the Salesforce MCP server — Records — read only (platform/sobject-reads) for most workspaces. The MCP endpoint fills in from the org's My Domain and type (production, sandbox, Developer Edition or scratch); check it against what Salesforce Setup shows. Choose Custom endpoint — another hosted server, or the URL Salesforce shows to paste a custom server's URL. Only https public hosts are accepted. Editing a connector later never rewrites its saved endpoint: a URL that is not one of the suggested servers is shown as Custom endpoint and only changes when you pick a different suggestion. A server that offers write tools is flagged; those tools stay refused unless you allow writes (see below).
5. Leave Authentication on Sign in with Salesforce (the default for a Salesforce connector). If your platform admin configured an External Client App on the server, leave the consumer key empty; otherwise enter the app's consumer key and, if the app requires one, its consumer secret. The secret is stored encrypted and never shown again.
6. Optionally add Extra headers, one per line, for non-secret values. Authorization, Cookie and session headers belong to MetaLens360 and are refused here. Header values are shown only to holders of Manage live data connectors; everyone else sees the header names with the values masked.
7. Leave Allow write-capable tools off unless the connector exists to make changes (see below). Leave Enabled on.
8. Click Add connector, then sign in. In the sign-in dialog choose where to sign in — the org's My Domain (recommended), the Production login or the Sandbox login — and click Sign in with Salesforce. Salesforce opens in the same tab; sign in as a user of that org and approve the app. You come straight back to the Live data tab, the row's Auth column reads Signed in, and hovering it shows Signed in as …, token valid until …. MetaLens360 renews the token itself from then on; Disconnect (click the Signed in chip) revokes and forgets it.
9. Click the Test (play) icon on the connector's row. MetaLens360 opens a session as the signed-in user and lists the server's tools, each badged Read-only or Write with a tooltip saying why it was classified that way. The row's status becomes Connected. Until a test succeeds the copilot does not use the connector.
10. Under Try a SOQL, choose the org, type a single SELECT and click Run live. The query runs through the same route the copilot uses — a SOQL tool on the connector, or else the org's own connection — capped at 200 rows and audited.

Any other MCP server that speaks Streamable HTTP is added the same way with Kind = Generic MCP; leave Org empty to make it usable with every org of the workspace, and choose the authentication it expects:

• Bearer token — a static token sent as Authorization: Bearer, stored encrypted and never shown again.
• Client credentials — client ID and secret, with an optional token URL and scope, for servers that support that grant. Salesforce's hosted servers do not.
• Org token (the org’s connection) — the org's own MetaLens360 credential, refreshed automatically. The endpoint must be on the org's own host or a Salesforce host (*.salesforce.com, *.force.com); for a server of your own use Bearer or Client credentials instead, because the org token must never leave Salesforce. Salesforce's hosted servers refuse it unless the connection itself was made through an External Client App with the mcp_api scope.
• None — for servers that are public or authenticate another way.

Ask live questions

1. Open the copilot and check the Org strip. Leave Auto selected, or pick Live to insist that the answer comes from the org.
2. Ask a record question — How many active users are there right now?, Which opportunities over 100k closed this quarter?, Show the 10 most recently modified accounts. While it reads, the status says Reading from the org….
3. Read the answer. The Live chip and the [V#] evidence name the connector or route and the time of the read. Open the evidence chip to see the exact SOQL or tool call that ran.
4. Rate the answer or save it as a learning as usual. A live figure is a snapshot; the learning you save is the method, not the number.

Allow a write-capable tool (optional)

By default every write-capable tool is refused outright and the copilot never sees it. If a connector exists to make changes:

1. On the Live data tab turn on the Writes switch for that connector and confirm the warning.
2. Ask the copilot for the change. It does not run it: the reply is an approval card naming the connector, the tool and the exact arguments, and it says I have not run it.
3. A holder of Manage live data connectors clicks Approve and run. The call runs once, exactly as shown, and the copilot answers from its result. Anyone else sees Ask an admin or architect to approve. Cancel declines it; nothing runs and the decline is audited too.
4. An approval is single-use and expires after ten minutes; a stale card fails closed with That approval has expired — ask again and approve the new request.

Example

Meera, an Architect at Acme, has acme-prod connected and synced. Her Salesforce admin activates platform/sobject-reads and creates an External Client App with the mcp_api and refresh_token scopes, PKCE, JWT-based access tokens and the callback URL https://metalens360.com/api/v1/live/oauth/callback. Meera opens Org Knowledge → Live data, clicks Add connector, names it Production MCP, picks acme-prod and the Records — read only server, leaves Sign in with Salesforce selected and clicks Add connector, then sign in. She chooses the org's My Domain, clicks Sign in with Salesforce, logs in as herself, approves the app and lands back on the tab with the row showing Signed in. Test lists seven tools, all Read-only, and the status turns Connected.

In the copilot, with Auto selected, Tomas (a Developer) asks How many active users are there right now? The answer is 1,284 active Users in acme-prod — Live from acme-prod via mcp (Production MCP) at 2026-10-26T09:14:02Z [V1], followed by The last Access 360 scan (20 Oct 2026) counted 1,290 active users [F1] — 6 fewer now. The chip under the answer reads Live. He then asks How many permission sets are there? and the answer comes from the index, labelled via MetaLens360 index (exact) — Auto never spends an org call on a metadata count.

Lee, a Viewer, asks the same live question and is told Your role cannot query live org data with a pointer to the Indexed source.

FAQs

Does live data replace the index?

No. The index is the fast, free, always-available source for everything about metadata, and the knowledge base is where your documents and learnings live. Live data adds the one thing a snapshot cannot give: records and people as they are right now. Auto uses each for what it is good at.

Who do live calls run as?

As the connector's credential — for Sign in with Salesforce, the person who signed the connector in; otherwise the stored token or the org's connection — never as the Salesforce user of whoever asks the question. Salesforce applies that user's object permissions, field-level security and sharing to every read, and the hosted server attributes the call to them in Salesforce's own audit trail. In MetaLens360 the audit row records you as the person who asked, and the sign-in itself is audited with who signed in.

How long does a sign-in last, and what if that person leaves?

Salesforce issues a short-lived access token and a refresh token; MetaLens360 renews the access token about a minute before it expires, without anyone's involvement, for as long as the refresh token is valid. Hovering Signed in shows who and until when the current token lasts. If the user is deactivated, their refresh token is revoked in Salesforce, or an admin removes their access to the External Client App, the next call fails with Sign in with Salesforce again and the connector's status turns to Error — click the chip and sign in as another user. Disconnect revokes the refresh token at Salesforce and forgets it.

Where does the consumer key come from?

From the External Client App your Salesforce admin created. A platform admin can configure one app for the whole MetaLens360 server (environment variables SF_MCP_CLIENT_ID and, if the app requires a secret, SF_MCP_CLIENT_SECRET), in which case connectors need no key; a connector can also carry its own consumer key and secret, which win over the server's. Changing a connector's key signs it out, because a refresh token belongs to the app that issued it.

Does Auto ever call the org for a metadata question?

No. Counts, inventories, dependencies and recent-change questions are answered from the index with no model and no org call. Only record, pipeline and user questions are routed live, and only when a tested, enabled connector exists for the org or its own connection can run SOQL.

Can I connect something that is not Salesforce?

Yes. Any MCP server that speaks Streamable HTTP can be added with Kind = Generic MCP. Its tools appear to the copilot as live:<connector>:<tool> and are classified read-only or write-capable like any other.

What is written to the audit log?

Adding, editing, testing and removing a connector; every live call with the tool name, object and the SOQL text that ran; every denied call and why; and every write proposal, approval and decline. Never a token, a secret, a header value or record values.

Why is a tool badged Write when it only reads?

MetaLens360 trusts the server's own read-only annotation first, then judges by the tool's name (get, list, query, describe read; create, update, delete, execute, send write) and treats anything it cannot place as write-capable, because a wrong guess in that direction costs a click and the other costs data. A holder of Manage live data connectors can correct a misclassified tool on the connector.

Can a tool result make the copilot do something?

No. Tool descriptions and tool results are wrapped as untrusted data before the model sees them, control characters are stripped and anything that looks like a credential is masked. The model can only propose tools MetaLens360 listed, with arguments MetaLens360 validates, and a write-capable one still stops for your approval.

Troubleshooting

"Only https:// MCP endpoints are allowed" or "Private, loopback and link-local IP addresses are not allowed"

Connectors may point only at public https hosts. Internal hostnames, private networks and the service's own metadata addresses are refused, and redirects are not followed.

The test fails with 401

The server rejected the credential. Per Salesforce documentation a hosted MCP server accepts only a JWT access token issued to an External Client App with the mcp_api scope. With Sign in with Salesforce a 401 means the token was revoked or expired and could not be renewed — click the Signed in chip and sign in again. With any other mode it means the credential is not such a token: an org's standard token, a legacy Connected App token or a token with the old beta scopes is refused; switch the connector to Sign in with Salesforce.

The test fails with 403

Salesforce accepted the sign-in but this user may not use the server: check that the user is permitted on the External Client App (permitted users, permission set or profile) and has access to the objects behind the server. After changing that, sign in again.

The test fails with 404

The server is not activated in Setup → MCP Servers, the server name is mistyped, or the endpoint names the wrong org type — a sandbox endpoint missing its sandbox segment, a Developer Edition org missing develop. Pick the server again from the Salesforce MCP server list to rebuild the URL. Activation takes up to about two minutes.

"Salesforce refused the sign-in: redirect_uri_mismatch" or "invalid_client"

The External Client App's callback URL does not match /api/v1/live/oauth/callback on your MetaLens360 site, the consumer key is wrong, or the app is newer than about 30 minutes and has not propagated yet. Fix the app or wait, then sign in again. The full reason is kept on the connector's status.

"Salesforce issued a session token instead of a JWT" or "The token lacks the mcp_api scope"

The External Client App is missing a setting: tick Issue JSON Web Token (JWT)-based access tokens for named users, and add the Access Salesforce hosted MCP servers scope. Then sign in again. MetaLens360 checks the token before storing it so a bad app cannot look like a working connector.

"You signed in to a different org than the one this connector is bound to"

You logged in at Salesforce as a user of another org. A connector is bound to one org and only accepts a sign-in from it; sign in again with a user of the bound org (choosing the org's My Domain as the login host avoids this).

"The sign-in request expired or was already used"

A sign-in must finish within ten minutes of clicking the button, and each attempt works once. Click Sign in with Salesforce again.

"No External Client App is configured"

Neither the connector nor the server has a consumer key. Enter the app's consumer key on the connector, or ask your platform admin to set SF_MCP_CLIENT_ID on the server.

Status says "Not tested yet — the copilot will not use it until a test succeeds"

Click the Test icon (for a Sign-in-with-Salesforce connector, sign in first). The copilot uses only connectors that are enabled and whose last test succeeded; a failing connector is retried in the background after ten minutes.

"No live connector is configured for acme-prod" or "Your role cannot query live org data"

You chose Live and nothing can read the org: either no connector is tested and enabled for it and its own credential no longer refreshes, or your role lacks Query live org data. Add or test a connector under Org Knowledge → Live data, reconnect the org, ask an admin for the permission, or switch to Indexed.

"Only a SELECT statement can run live", "LIMIT must be a positive whole number" or an object "holds credential or security telemetry"

Live SOQL is one SELECT: no DML, no FOR UPDATE, no comments or semicolons, LIMIT capped at 200 (50 is added when you give none), and objects such as login history, sessions and OAuth tokens are never queried.

"That approval has expired" or "That approval was already used"

An approval is single-use and valid for ten minutes. Ask the question again and approve the new card.

The answer ends with "The live query failed (…); this is the indexed figure"

Auto tried the org first, the call failed (timeout, expired credential, server error) and the copilot fell back to the index and said so. The evidence list shows the failed call; test the connector to see the server's message.

Related articles

• Use the AI assistant
• Build org knowledge the copilot can cite
• Connect a Salesforce org
• Roles and permissions