What you are setting up

The Precursive AI MCP server lets an AI assistant such as Claude work with your Zen Agents in conversation - discovering which agents exist, reading the latest insight for a record, reading or refreshing the underlying context data, and generating a new insight on demand. Everything runs as the connected Salesforce user, so sharing rules and field-level security are enforced on every request.

For what your users get out of it, see Connecting Claude to Precursive AI.

There are three jobs to do, and all are one-off:

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

Step 1 - Deploy the MCP server

You need the Precursive AI Insights Admin permission set. It carries the custom permission that controls access to this screen, so without it the option is not available to you.

1. Open the Precursive AI app and go to AI Settings.
2. Select the External Services tab, then the Precursive AI MCP Server tab within it.
3. Choose Set up MCP Server.

The tools table then shows every tool and its status:

• Available - deployed and ready to use.
• Pending setup - the tool could not be attached yet because the API behind it is not registered in the org. Run the sync again; if a tool stays pending, see Troubleshooting below.
• Not deployed - not yet created.

After every package upgrade

Come back to this screen and choose Update Tools. The sync is safe to repeat - it adds tools that are new in the release, updates any that have changed, and removes those that have been retired. New capability will not appear for your users until you run it.

Finding your endpoint URL

Once the server exists, choose Open in Setup. This opens the MCP Server record in Salesforce Setup, which shows the connection endpoint for your org. Take the endpoint from this page rather than typing one in - it is the authoritative value. Keep it to hand; you need it in Step 3.

It takes the form https://api.salesforce.com/platform/mcp/v1/PrecursiveAiMcp, with an additional /sandbox segment for a sandbox org: https://api.salesforce.com/platform/mcp/v1/sandbox/PrecursiveAiMcp.

Step 2 - Create the External Client App

Claude authenticates to your org over OAuth, which requires an OAuth app in the org. This is not shipped with the package - the underlying metadata cannot be packaged - so each org creates its own. It takes a few minutes.

The app is a public client using PKCE, with no client secret. The Consumer Key is a public identifier rather than a credential.

1. Go to Setup > App Manager (called External Client App Manager in some orgs) and choose New External Client App.
2. Name it - Precursive AI MCP is a sensible choice - and set a contact email.
3. Enable OAuth settings.
4. Set the Callback URL. For Claude this must be exactly https://claude.ai/api/mcp/auth_callback. Other clients use their own values - see the table below.
5. Add exactly two OAuth scopes: Access MCP servers (mcp_api) and Perform requests at any time (refresh_token).
6. Under security settings, select both Issue JSON Web Token (JWT)-based access tokens for named users and Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows. Deselect everything else - in particular, do not require a secret for the web server or refresh token flows, and do not enable the client credentials flow.
7. Save, then open the app's OAuth settings and copy the Consumer Key. You need it in Step 3.

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

Callback URLs by client

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

Allow up to 30 minutes

A newly created External Client App can take up to around 30 minutes to become operational for MCP. If the connection fails immediately after you create it, this is almost always why. Wait and try again before changing anything.

Step 3 - Add the connector in Claude

Adding the connector yourself means your users never have to handle the endpoint URL or the Client ID. They will simply see Precursive AI MCP in their list of connectors and sign in.

1. In Claude, go to Settings > Connectors and choose Add custom connector.
2. Name it 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 blank.
5. Choose Add, then Connect to authorise your own access and confirm the setup works. You should see the Precursive AI tools listed.

On Team and Enterprise plans, add the connector at organisation level so it is available to everyone in your Claude workspace. You may 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 they can add it once themselves.

Sharing the connector does not share access

This is worth being clear about. What is shared is the connector definition - the address of your MCP server and the identifier of the OAuth app. It grants nothing on its own.

Every user still authorises individually with their own Salesforce login, and every request they make runs under their own permissions. Two people using the same connector see different data, exactly as they do in Salesforce.

Tell your users they are ready

Once the connector is in place, point your users at Connecting Claude to Precursive AI. All they need to do is find Precursive AI MCP in their connector list, choose 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, Insights Builder and Insights Admin all grant access to the Zen Agent tools. Anyone who can already see insights can use them.
• Precursive AI Insights Admin alone can deploy or update the server.

Setting this up grants no additional object or field access. Every user's reach stays bounded by the permissions they already have.

The "Continue in..." menu

Users can hand an insight over to an assistant directly from the Precursive AI component, using Continue in... in the Zen Agent dropdown. The list of assistants is driven by the AI Assistant Handoff URL custom metadata type.

Claude and ChatGPT ship as active records, so the menu works as soon as the package is installed. You can:

• Turn an assistant off by clearing Active.
• Change the order they appear in with Order.
• Add another assistant with a URL template that starts with https:// and contains a {PROMPT} token, which is replaced with the generated prompt.

Note that the handoff and the MCP server are independent. The menu will still open a conversation if the MCP server has not been deployed - the assistant simply will not be able to load the context, and the user is told so.

Security and data handling

• All tools run in user mode as the connected user. There is no elevation and no shared service account. Sharing rules, object permissions and field-level security are enforced on every call.
• The handoff link is security-enforced too. A user can only build a handoff for an insight they can already see, and the link carries identifiers only - no insight content. The assistant fetches the data itself, under that user's own login.
• Because reach is bounded by each user's existing permissions, the MCP server does not widen who can see what. It changes how they reach it.

See also Precursive AI Data Privacy and Security and Insight Sharing and Access Control.

Reference - the tools

These are the tools the server exposes. You do not need to configure them individually; they are listed here so you know what a connected assistant is able to do.

Tool	Type	What it does
zen_list_agents	Read	Lists the active Zen Agents so an assistant can pick 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 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 an agent's context data for one record without regenerating the 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	Traverses 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

Symptom	Cause and fix
The connection fails, shortly after you created the External Client App	A new app takes up to around 30 minutes to become operational for MCP. Wait, then try again.
An error about an invalid client during sign-in	The OAuth Client ID on the connector must be the Consumer Key of the External Client App in the same org that hosts the MCP server. Re-copy it, and confirm no client secret is set.
A redirect or callback mismatch error	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 rather than to the organisation, or custom connectors are not enabled for the workspace. Check your Claude plan and workspace settings.
A tool stays on Pending setup	The API behind that tool is not registered in the org yet. Run Update Tools again. If it persists after an upgrade has fully completed, raise it with Precursive support.
An assistant reports that a field does not exist, when it clearly does	Field-level security. Tool queries run in user mode, 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 active AI Assistant Handoff URL records. Check that at least one record has Active set and a valid URL template.

Related articles

• Connecting Claude to Precursive AI - the end user guide to share with your team.
• Getting Started with Precursive AI - the key concepts behind Zen Agents, insights and actions.
• Precursive AI Data Privacy and Security
• Insight Sharing and Access Control