TaskRay MCP: Administration Installation & Setup

Beta TaskRay MCP is available now as part of our beta program. See Enroll in the Beta below to get started.

Not the same as TaskRay AI This guide is for TaskRay MCP, which connects external AI tools (Claude Code, claude.ai, ChatGPT, Microsoft Copilot, and Agentforce) to your TaskRay data via MCP. It is a different feature from TaskRay AI, the prebuilt in-app Agentforce agent, which has its own package, permission sets, and install. Agentforce can sit on either side of that line, and the FAQ explains how.

This guide walks a Salesforce Admin through installing the TaskRay MCP - Connector package, locking down its OAuth app to a secure baseline, granting users access, and sharing the connection link. Once complete, your team can link their own AI tool to their TaskRay data, and each connection is scoped to that user's own Salesforce permissions.

This guide covers:

What ships in the package
Enrolling in the beta
Installing it
Required post-install security configuration
The permission sets involved and what each does
How write approvals work
Optionally exposing custom fields to TaskRay MCP
Sharing the connection link, including shared setup for Team/Enterprise AI workspaces
Frequently asked questions

Overview

Per-user and least-privilege. Every connection is scoped to that user's own Salesforce permissions. Connecting never grants access beyond what the user already has.
Nothing to host. The MCP server is a shared, publisher-hosted deployment. There is no server for you to stand up, and its address is compiled into the package (not subscriber-editable).
Server-side token custody. The Salesforce refresh token stays on the server, and your AI tool only ever holds an opaque token scoped to the minimum Api OAuth permission.

What Ships in the Package

Component	What it is
TaskRay Agents External Client App	The OAuth client. Its OAuth/App policies are not packaged, so you configure them post-install (below).
TaskRay Agents - User permission set	Grants Apex class access and API Enabled, which every MCP tool call needs. Assign it to anyone who should connect.
TaskRay Agents - Admin permission set	Admin-only, separate from the User set. It unlocks the TaskRay AI Assistant Fields config screen and grants no data access of its own.
TaskRay Agents - Ungated Writes permission set	Optional, admin-assigned to an individual user. It lets that user's deletes and bulk changes execute immediately instead of queuing for approval (see Step 3).
TaskRay AI Assistant Fields tab	The admin screen for opting your org's custom fields into visibility for TaskRay MCP. Standard and TaskRay-managed fields are exposed by default, and your custom fields are opt-in.

Enroll in the Beta

Getting started with TaskRay MCP beta begins with a quick enrollment.

Complete the beta enrollment form and sign the participation agreements. [link/contact, confirm with your TaskRay contact before publishing]
Once your enrollment is completed and approved, you'll receive an email with your install link for Step 1 below.

Thank you for helping us shape TaskRay MCP! As a beta participant, you will be asked to share feedback along the way through surveys and contact with your TaskRay account team. Your feedback and time is valuable and will inform our roadmap for TaskRay AI.

Step 1: Install the Package

Once enrolled, install from the install link you were given (an AppExchange listing, if used, produces the same flow).

SCREENSHOT — the Salesforce install screen; choose Install for Admins Only. (Org name redacted.)

Open the install link and sign in as a System Administrator. Use the production link, or the sandbox-org equivalent, matching your target org.
On the install screen, choose "Install for Admins Only."
Click Install and wait for confirmation.

Why Admins Only Access is granted entirely through permission sets (below), not profiles, so there is no reason to push components onto profiles at install time. You provision real users afterward by assigning permission sets, which is also where you pre-authorize them on the External Client App.

Important Install the package. Do not source-deploy its components, especially the External Client App. Source-deploying it disturbs its packaged install state and breaks OAuth with an OAUTH_EC_APP_NOT_FOUND error. Always distribute and upgrade via package install.

Step 2: Post-Install Security Configuration

The External Client App's OAuth policies are not carried by the package and reset to permissive defaults on every install. Complete the steps below before granting users access.

2.1 Lock Down App Authorization

By default the app installs with Permitted Users = "All users may self-authorize," letting any user mint a token for the MCP server. Restrict it to approved users.

a. Create a local permission set for app access

From Setup, navigate to Permission Sets | New. Name it, for example, "TaskRay Agents App Access."
Save it. It needs no specific entitlements, and its only purpose is app authorization.

The most common setup mistake Use your own local permission set here, never the packaged TaskRay Agents - User set. Attaching a managed permission set to the managed app fails to save with a SetupEntityAccess…MANAGED_INSTALLED error. The packaged set is still required, just for a different purpose (Apex/API access, see step c).

b. Set the app to admin-approved and pre-authorize your permission set

From Setup, navigate to External Client App Manager | TaskRay Agents | Edit Policies.
Under OAuth Policies, set Permitted Users → "Admin approved users are pre-authorized."
Two multi-select pickers appear (Profiles, Permission Sets). In the Permission Sets picker, move "TaskRay Agents App Access" from Available to Selected.
Click Save.

This is the step that actually authorizes users Choosing the "Admin approved" dropdown value alone authorizes no one. Every user gets "access denied" until a profile or permission set is moved into Selected. If the save fails with a SetupEntityAccess…MANAGED_INSTALLED error, you selected the packaged set by mistake, so use your local set instead.

c. Assign both permission sets to each MCP user

SCREENSHOT — a user with both TaskRay Agents App Access and TaskRay Agents - User assigned. (Username redacted.)

Permission set	Type	What it grants
TaskRay Agents App Access	Local	Authorizes the app (the ECA pre-authorization from step b)
TaskRay Agents - User	Packaged	Apex class access and API Enabled, required for every MCP tool call

Both are required Without App Access, OAuth is denied. Without TaskRay Agents - User, API Enabled is missing. If sign-in succeeds but tool calls fail, the user is missing the TaskRay Agents - User set.

2.2 Refresh-Token Policy

Under External Client App Manager | TaskRay Agents | Edit Policies | OAuth Policies.
Set Refresh Token Policy → "Expire refresh token after" an inactivity window matching your security tolerance.

The default on install is 365 days. Tighten it. The MCP server holds a long-lived token on the user's behalf, so a shorter idle window limits exposure.

2.3 IP Relaxation

Set IP Relaxation → "Relax IP restrictions." This is the correct setting, not a security shortcut:

The MCP server has dynamic egress IPs, so there is no fixed range to add to Login IP Ranges. Enforcing one would block the integration outright.
Login IP Ranges govern where a session originates. Your users' interactive sign-in still happens from their own browser and stays subject to all your normal login policies, MFA included. Only the server's background API calls come from the cloud host.

In short For a cloud-hosted server integration, relaxing IP restrictions is the standard, supported configuration. Real protection comes from admin-approved users, per-user least privilege, and short refresh-token expiry, not from IP.

2.4 Verify

SCREENSHOT — a provisioned test user who has completed the connection (the connection page's connected state). (Token and tenant code redacted.)

Confirm a user with both permission sets can open the connection page and complete OAuth.
Confirm a user without App Access is denied.
Confirm a user without TaskRay Agents - User can sign in, but their tool calls fail.

Step 3: Understand Write Approvals

TaskRay MCP doesn't execute deletes or large bulk changes directly. It queues them for a human to approve first, and nothing is written until someone confirms it.

Only the person who proposed the action can approve it, not any other user, and not an admin on their behalf. Approving requires signing back in as that same person.
Unapproved requests expire after 24 hours by default. An expired request was never executed.

Letting a trusted user skip approval Assign a user the optional TaskRay Agents - Ungated Writes permission set to let their deletes and bulk changes execute immediately instead of queuing. This is a deliberate, per-user grant an admin makes, and a user can't opt themselves out.

Step 4 (Optional): Expose Custom Fields to TaskRay MCP

By default TaskRay MCP can read standard and TaskRay-managed fields, but none of your org's own custom fields. This step is optional. Skip it and only standard and managed fields are exposed, which is the safe default.

a. Assign the TaskRay Agents - Admin permission set

This config screen is gated by a third, separate permission set from the two above. Assign TaskRay Agents - Admin to yourself or whoever curates field exposure. It grants the config tab and its Apex, and no data access of its own.

b. Open the TaskRay AI Assistant Fields tab

SCREENSHOT — the TaskRay AI Assistant Fields tab (object picker + field list), initial state. (Org redacted.)

From the App Launcher, search for "TaskRay AI Assistant Fields" and open it. Only users with the TaskRay Agents - Admin set can see the tab or its contents.

c. Opt fields in

SCREENSHOT — a couple of custom fields toggled on and Saved. (Any customer-specific field labels redacted.)

Pick a TaskRay object. The core planning objects (Projects, Tasks, Task Groups, Checklist Items, Checklist Groups) come first.
Toggle on the custom fields TaskRay MCP may read, then Save.

Give it up to 10 minutes The exposed-field list is cached per org, so a change takes up to 10 minutes to reach TaskRay MCP. The same delay applies to revoking a field. It stays readable and writable by TaskRay MCP until the cache turns over, so revoking is not an immediate containment action. To close a field off right now, remove the user's field-level security instead, which is enforced on every request. Note the blast radius: removing field-level security closes the field for that user everywhere, not just for TaskRay MCP.

Watch the PII flag Fields whose name or type suggests personal data (email/phone types, or keywords like SSN, address, salary) are marked as likely PII, a prompt to pause before exposing them, not a guarantee. You make the call.

Step 5: Share the Connection Link

There is no in-org button to place. Users connect from the publisher-hosted connection page:

Production orgs: https://mcp.taskray.com/oauth/login
Sandbox / scratch orgs: https://mcp.taskray.com/oauth/login?sandbox=true (so sign-in goes to test.salesforce.com)

Signing in there gives the user a ready-to-use claude mcp add command (Claude Code) and their org's connector URL (web tools). Hand end users the connection guide for the tool they use: Claude Code, claude.ai, ChatGPT, Microsoft Copilot Studio, or Salesforce Agentforce.

Step 6: How Your Users Connect

Claude Code. A ready-to-run command pasted into a terminal once.
Web tools (claude.ai, ChatGPT). A connector URL pasted into the tool's connector settings, which signs in with Salesforce automatically. The same URL works in every web tool.
Microsoft Copilot Studio. Maker-configured, so a maker adds the connector once and each user signs in individually on first use. See the companion Copilot Studio Setup Guide.
Salesforce Agentforce. Register TaskRay's connector URL as an external MCP server in Agentforce, then each user signs in with their own Salesforce login. This is Salesforce's own agent platform acting as an MCP client, and it is separate from the prebuilt TaskRay AI agent (see the FAQ).

Setting Up a Shared Web Connector (Team / Enterprise)

In claude.ai and ChatGPT Team/Enterprise, custom connectors are added by a workspace admin once for the whole workspace, and each member then authenticates individually.

Enable custom connectors in your AI tool. They're off by default on most Enterprise plans, and this is the gate that blocks everyone, including admins, until enabled.
Get your org's connector URL. As any provisioned user, open the connection page and sign in once. The connected page shows your org's connector URL, so copy it.
Add it as the workspace connector in your AI tool.
Tell your users to sign in. They open the now-visible TaskRay connector and complete their own Salesforce sign-in. There is no URL for them to paste.

Visible to all does not mean usable by all A workspace connector is visible to every member, but only users you've provisioned in Salesforce (Step 2) can complete sign-in. An unprovisioned member will see the connector and hit "access denied," which is the per-user gate working as intended.

One connector URL is one Salesforce org The connector URL pins to a single Salesforce org. A workspace whose members span multiple Salesforce orgs needs a separate connector per org.

That's it! Your team can now connect their own AI tools to TaskRay.

What You Can Do with TaskRay MCP

Get a live project status in seconds. Ask your AI to summarize any project and get a plain-language rundown of what's complete, what's blocked, and what's due next, with no clicking required.
Triage your week in one prompt. Ask what you own this week across all your projects, ordered by deadline with blockers flagged. Your Monday morning in one sentence.
Spin up a new project from a template. Name the customer, name the template, and give a start date, and your AI creates the full project structure in TaskRay and handles the scheduling.
Log and reconcile time without the grind. Describe your week in plain language and the assistant maps it to tasks, drafts the entries, and waits for your approval before filing anything.
Walk into every customer call prepared. Pull a project status, recent email threads, and notes from the last call into a single brief before you get on the phone.

See the full prompt guide →

Frequently Asked Questions

Q. Agentforce comes up in two places. How do TaskRay MCP, TaskRay AI, and Agentforce fit together?
They are related but distinct. TaskRay MCP (this product) connects an AI tool to your TaskRay data through an MCP server, and the surfaces the beta supports are Claude, Claude Code, Microsoft Copilot, Agentforce, and ChatGPT. Agentforce connects the same way the other web tools do: you register TaskRay's connector URL as an external MCP server in Agentforce, and each person signs in with their own Salesforce login. TaskRay AI is a separate product: a prebuilt Agentforce agent that TaskRay ships as its own managed package, with its own permission set and setup. It runs inside Salesforce and does not use the MCP connector described here. So "Agentforce" can mean either connecting your own Agentforce agent to TaskRay MCP or installing the prebuilt TaskRay AI agent, and you can use either or both.

Q. Sign-in opened the production login instead of my sandbox. What happened?
Use the ?sandbox=true connection link for sandbox and scratch orgs (Step 5). The production link always sends sign-in to login.salesforce.com.

Q. A user gets "access denied" when they try to sign in. What's going on?
They aren't pre-authorized on the External Client App yet. Confirm their App Access permission set is in the Selected column (2.1.b) and that it's actually assigned to them (2.1.c).

Q. Sign-in works, but a user's tool calls fail. Why?
They're missing the TaskRay Agents - User permission set, which grants the API Enabled entitlement every tool call needs.

Q. I got a SetupEntityAccess…MANAGED_INSTALLED error while saving. What do I do?
You selected the packaged permission set as the ECA's authorization holder. Use your local set instead (2.1.a).

Q. I'm seeing an OAUTH_EC_APP_NOT_FOUND error. What caused it?
The External Client App was source-deployed rather than installed via package, which corrupts its install state. Reinstall via package install only (Step 1).

Q. TaskRay MCP is connected, but it can't see or update records I expected. Is something wrong?
No, this is working as designed. Access always mirrors the connecting user's own Salesforce permissions. Adjust that user's field-level security or sharing, not TaskRay MCP.

Q. What happens if I revoke a user's access later?
Deactivating the Salesforce user, or removing either of their two permission sets, ends their access right away. The connection has no independent life of its own.

Q. Someone asked TaskRay MCP to delete something (or make a bulk change), and it says the action is pending approval. What does that mean?
Nothing has been written yet. Deletes and large bulk changes are queued for approval before they execute. Only the person who proposed the action can approve it, not any other user and not an admin on their behalf, by signing back in to confirm. If it isn't approved within 24 hours, the request expires and nothing happens.

Q. Can I let a trusted user skip the approval step?
Yes. Assign that user the optional TaskRay Agents - Ungated Writes permission set (Step 3). Their deletes and bulk changes will then execute immediately instead of queuing. This is a deliberate grant an admin makes per user, and a user can't opt themselves out.

Have a question that isn't answered here? Contact TaskRay Support with the exact error text, which org (production or sandbox), and which AI tool.