What you set up

The Precursive AI MCP Server lets an AI assistant such as Claude work with your Zen Agents in a conversation. The assistant can find the available Agents, read the latest Insight for a record, read or refresh the underlying context data, and generate a new Insight. Everything runs as the connected Salesforce user, so each person reaches only the records and Insights that their own Salesforce access allows.

For what your users can do with it, see Connecting Claude to Precursive AI.

The setup has three one-time tasks:

• Deploy the MCP Server in your org from Precursive AI Settings.
• Create an External Client App so that Claude can authenticate to your org over OAuth.
• Add the connector in Claude, so that your users only need to sign in.

Step 1: Deploy the MCP Server

You need the Precursive AI Admin permission set. It includes the custom permission that controls access to this screen.

1. Open Precursive AI Settings.
2. Select the External Services tab, and then select the Precursive AI MCP Server tab.
3. Select Set up MCP Server.

   

The tools table shows each tool and its status:

• Available: the tool is deployed and ready to use.
• Pending setup: the API behind the tool is not registered in the org yet, so the tool is not attached. Run the sync again. If the tool stays pending, see Troubleshooting.
• Not deployed: the tool does not exist yet.

Find your endpoint URL

After the server exists, select Open in Setup. The MCP Server record opens in Setup and shows the connection endpoint for your org. Copy the endpoint from this page instead of typing it, because this page holds the correct value. You need it in Step 3.

The endpoint has the form https://api.salesforce.com/platform/mcp/v1/PrecursiveAiMcp. A sandbox org adds a /sandbox segment: https://api.salesforce.com/platform/mcp/v1/sandbox/PrecursiveAiMcp.

After every package upgrade

After each upgrade, return to this screen and select Update Tools. The sync adds the tools that the upgrade includes, updates tools that changed, and removes retired tools. You can run it as often as you need. Your users get new capabilities only after you run it.

Step 2: Create the External Client App

Claude authenticates to your org over OAuth, which needs an OAuth app in the org. Salesforce cannot include this app in a package, so each org creates its own. It takes a few minutes.

The app is a public client that uses PKCE (Proof Key for Code Exchange), with no client secret. The Consumer Key is a public identifier, not a credential.

1. Go to Setup > App Manager, which some orgs call External Client App Manager, and select New External Client App.
2. Enter a name, for example Precursive AI MCP, and a contact email.
3. Turn on the OAuth settings.
4. For Callback URL, enter https://claude.ai/api/mcp/auth_callback exactly. Other clients use their own values, as shown in the table that follows.
5. Add exactly two OAuth scopes: Access MCP servers (mcp_api) and Perform requests at any time (refresh_token).
6. In the security settings, select Issue JSON Web Token (JWT)-based access tokens for named users and Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows.
7. Clear every other security setting. Leave the secret requirement off for the web server and refresh token flows, and leave the client credentials flow off.
8. Select Save.
9. Open the OAuth settings of the app and copy the Consumer Key. You need it in Step 3.

If your org restricts app access, also pre-authorize the profiles or permission sets that should be able to use the app.

Callback URLs by client

Each MCP client needs its own callback URL on the app:

Client	Callback URL
claude.ai and Claude Desktop	https://claude.ai/api/mcp/auth_callback
Claude Code	http://localhost:38000/callback
Cursor	cursor://anysphere.cursor-mcp/oauth/callback
Postman	https://oauth.pstmn.io/v1/callback

ℹ️ Note: A new External Client App can take up to 30 minutes to work with MCP. Wait before you change anything.

If the connection fails right after you create the app, this delay is the most likely cause. Wait, and then try again.

Step 3: Add the connector in Claude

When you add the connector yourself, your users do not need the endpoint URL or the Client ID. They see Precursive AI MCP in their list of connectors and sign in.

1. In Claude, go to Settings > Connectors, and then select Add custom connector.
2. For the name, enter Precursive AI MCP.
3. Paste the endpoint URL from Step 1.
4. Open Advanced settings, and paste the Consumer Key from Step 2 into the OAuth Client ID field. Leave the client secret empty.
5. Select Add.
6. Select Connect to authorize your own access and confirm that the setup works. The Precursive AI tools appear in the list.

On Team and Enterprise plans, add the connector at the organization level so that everyone in your Claude workspace can use it. You might need to allow custom connectors for the workspace first. On plans where connectors are per user, give each user the endpoint URL and the Consumer Key so that they can add the connector once.

Sharing the connector does not share access

When you share the connector, you share only the connector definition: the address of your MCP Server and the identifier of the OAuth app. The definition grants no access on its own.

Each user authorizes with their own Salesforce login, and each request runs under their own permissions. Two people who use the same connector see different data, as they do in Salesforce.

Tell your users they are ready

When the connector is in place, send your users to Connecting Claude to Precursive AI. To start, they find Precursive AI MCP in their connector list, select Connect, and sign in to Salesforce.

Who can use it

There is no separate MCP permission set. Access follows the permission sets you already assign:

• Precursive AI Standard, Precursive AI Insights Builder, and Precursive AI Admin all give access to the Zen Agent tools. When a user asks about an Insight they have not opened in Salesforce yet, the tools check their access first, the same way the record page does, and return the Insight only if they pass.
• Only Precursive AI Admin can deploy or update the server.

The setup grants no extra object or field access. Each user can reach only what their own Salesforce access allows, including any access that System Mode gives them.

The Continue in menu

Users can hand an Insight over to an assistant from the Precursive AI component, with Continue in in the Zen Agent menu. The AI Assistant Handoff URL custom metadata type controls the list of assistants.

Claude and ChatGPT are included as active records, so the menu works as soon as you install the package. You can change the list as follows:

• To turn off an assistant, clear Active.
• To change the order of assistants that you add, set Order. On the Claude and ChatGPT records, you can change only Active.
• To add an assistant, create a record with a URL template that starts with https:// and contains a {PROMPT} token. Precursive AI replaces the token with the generated prompt.

The handoff and the MCP Server work independently. If the MCP Server is not deployed, the menu still opens a conversation, but the assistant cannot load the context, and Precursive AI tells the user.

Security and data handling

The MCP Server and the handoff menu follow the same access rules as the rest of Precursive AI:

• All tools run as the connected user, with no elevated access and no shared service account. Sharing rules, object permissions, and field-level security apply to every query.
• The tools return only Insights that the user can open. If the user has not opened an Insight before, the tools run the same access check as the record page, and a refusal is recorded like any other. The context snapshot of an Insight is returned as stored, so a user who can open an Insight, including through System Mode, receives all the data in it.
• A user can create a handoff only for an Insight they can already see. The handoff link carries only identifiers, not Insight content. The assistant fetches the data itself, with the Salesforce login of the user.
• The MCP Server does not change who can see what. It changes only how people reach it.

For more information, including how users sign in, what data reaches the assistant, and what the server costs, see Precursive AI MCP Server security and data privacy, Precursive AI data privacy and security, and Insight sharing and access control.

Reference: the tools

The server provides the following tools. You do not need to configure them. The table shows what a connected assistant can do:

Tool	Type	What it does
zen_list_agents	Read	Lists the active Zen Agents, so an assistant can choose the right one.
zen_get_latest_insights	Read	Returns the most recent Insight and recommended actions for records.
zen_get_latest_context	Read	Returns the data snapshot that an Insight was generated from, for one record.
zen_get_run_status	Read	Reports whether an Agent run is in progress, complete, or failed.
zen_run_agent	Action	Runs a Zen Agent on records to build context and generate a new Insight.
zen_refresh_context	Action	Refreshes the context data of an Agent for one record without generating a new Insight.
run_soql	Standard	Runs a read-only query, used to find the records an Agent applies to.
get_object_schema	Standard	Returns object and field schema metadata.
get_related_records	Standard	Goes from a record to its related records.

Read and Standard tools only read data. The two Action tools generate or refresh Precursive AI data. Neither creates or edits your Salesforce business records.

Troubleshooting

The following table lists common problems and how to fix them:

Symptom	Cause and fix
The connection fails shortly after you create the External Client App.	A new app can take up to 30 minutes to work with MCP. Wait, and then try again.
Sign-in shows an invalid client error.	The OAuth Client ID on the connector must be the Consumer Key of the External Client App in the org that hosts the MCP Server. Copy it again, and confirm that no client secret is set.
A redirect or callback mismatch error appears.	The callback URL on the app must match the client exactly. For Claude, it is https://claude.ai/api/mcp/auth_callback.
Sign-in succeeds, but no tools are available.	The app is missing the mcp_api scope. Without it, a client can authenticate but cannot reach the MCP Server.
Users cannot see Precursive AI MCP in their connector list.	The connector was added to your own account instead of the organization, or custom connectors are not allowed in the workspace. Check your Claude plan and workspace settings.
A tool stays on Pending setup.	The API behind the tool is not registered in the org yet. Select Update Tools again. If the tool is still pending after an upgrade completes, contact Precursive Support.
An assistant reports that a field does not exist, but it does.	Field-level security hides the field. Tool queries run with the permissions of the user, so a field the user cannot read is invisible rather than an error. Grant read access on the field in the relevant permission set.
The Continue in menu is empty for users.	No AI Assistant Handoff URL records are active. Check that at least one record has Active selected and a valid URL template.
An assistant reports that no Insight was found for a record that has one.	The user may not pass the access check for that Insight, or the Agent has not run for the record yet. Run Check Access on the Insight for that user to see what blocks them. When an assistant asks about many records at once, the tools check a few at a time, so the assistant may need to ask again for the rest.

Related articles

These articles cover how users connect, the key concepts, and data access:

• Connecting Claude to Precursive AI: the end-user guide to share with your team.
• Get started with Precursive AI: the key concepts behind Zen Agents, Insights, and Actions.
• Precursive AI data privacy and security: how Precursive AI handles your data.
• Insight sharing and access control: how Precursive AI decides who can see each Insight.