Remote MCP Server (AI clients)

The Remote MCP Server lets AI assistants that speak the Model Context Protocol (MCP) -- ChatGPT, Claude (web, desktop and Claude Code), Cursor and GitHub Copilot -- query what aprity knows about your Salesforce org. Once connected, the assistant can look up objects, fields, rules, automations, permissions and integrations, answer questions and draft user stories, all from your latest aprity scan.

Users sign in with their own Salesforce login, through your org's own Connected App. There is no aprity account to create and no token to copy.

What the AI client can do

The server exposes a set of read-only tools. The AI client picks the right one for the question; users do not need to name them. The main ones:

Tool	What it returns
ask_help_agent	A synthesized answer to an open question about the org, with citations.
analyze_change_request	For a change request or an impact question ("add a control before X"): the components involved, the existing rules, the execution order, dependencies, impact and open questions.
search_documented_objects, search_org_documentation	Find objects, rules, processes or components from business terms.
get_object_business_rules, describe_field, list_fields, get_record_types	Precise lookups on an object, its fields and its record types.
get_execution_order, get_rule_test_scenarios	What runs when a record of an object is created, updated, deleted or restored, and in what order; the conditions and effects of each rule.
get_object_permissions, get_record_visibility, get_record_ownership_rules	Who can read or edit an object, which records are shared with whom, how records are assigned.
get_metadata_dependencies, compute_change_impact	What depends on a component, and what a change would affect.
get_integrations, get_business_processes	External systems and integration flows; the functional processes documented for the org.
generate_user_story	A user story with Given / When / Then acceptance criteria, when the user explicitly asks for one.

Other tools cover more specific needs: the org's object list and metadata, valid picklist combinations per record type, Apex class structure, OmniStudio processes and rate tables, and the themes your team defined in the portal.

The server also tells the AI client that aprity is the source of truth for your org, so questions about your objects, fields or automations reach aprity even when the user does not mention it. Generic Salesforce questions ("how does a trigger work?") are answered from the assistant's own knowledge.

The tools read the scan data, never your org live. Run a new scan when your org has changed.

Plan availability

The Remote MCP Server is available on the Intelligence and Trial plans. It is not included on Documentation.

Plan	Tool-call quota
Documentation	Not included
Intelligence	2,000 tool calls per month
Trial	25 tool calls for the whole trial

Each call the AI client makes to an aprity tool counts as one tool call. A single question can lead the assistant to make several calls. The quota is shared by every user and every AI client connected to your organization. On Intelligence it resets on the first day of each calendar month.

See Plan Comparison for the full feature matrix.

Administrator setup (once per org)

The sign-in runs against the Connected App (External Client App) you created for aprity when you set up the package. Three settings on that app must be in place:

1. Callback URL. The app's Callback URL list must contain the MCP callback line, https://mcp.aprity.ai/v1/mcp/oauth/sf-callback. The aprity setup assistant (in the aprity tab of Salesforce) lists the exact callback URLs for your org, one per line; the third line is the one used by AI clients. A missing line shows up as a Salesforce redirect_uri_mismatch page at sign-in.
2. Scopes. The scopes the setup assistant marks as needed for the portal (openid and the identity URL scope) are also needed for AI clients.
3. Permitted users. The app's Permitted Users policy is "Admin approved users are pre-authorized". Add the profiles of the users who will connect an AI client, as you did for portal users. A user outside those profiles is refused by Salesforce.

The web portal must also be published for your org: the MCP address is specific to your portal.

See Connected App Setup for the full Connected App configuration.

Get your MCP address

In the aprity web portal, open the account menu, then Connectors (customer administrators only). The AI assistants · MCP card shows your organization's address, in the form:

https://mcp.aprity.ai/v1/mcp/t/<your-slug>

Use Copy URL, or expand Client configuration to copy a ready-made configuration block. Share the address with your users: it is not a secret and carries no credential.

Connect an AI client

1. Add aprity as a remote MCP server in the AI client, using your organization's MCP address.
2. The client opens a browser window: sign in with your usual Salesforce credentials for the org aprity documents, and approve the access.
3. The client receives its access automatically. The aprity tools then appear in the client.

Pick the guide for your client:

• ChatGPT
• Claude.ai (web)
• Claude Desktop
• Claude Code (CLI)
• Cursor
• GitHub Copilot (VS Code, Copilot desktop app, Copilot CLI)

Any other client that supports remote MCP over HTTP with OAuth sign-in (authorization code with PKCE and dynamic client registration) should work the same way.

Disconnect

• One user, one client: remove the aprity server from the client. The client's access expires on its own (access tokens last one hour, refresh tokens 30 days).
• The whole organization: an administrator can cut off every AI client at once by disabling the aprity Connected App in Salesforce, or by removing the users' profiles from its permitted users.

Legacy access tokens

Organizations that connected AI clients with access tokens before the Salesforce sign-in was introduced can review those tokens in Connectors > AI assistants · MCP > Legacy access tokens, and Revoke the ones no longer needed. Revoking a token cuts off the clients using it immediately. New tokens can no longer be created: use the Salesforce sign-in instead.

Privacy and security

• Your Salesforce credentials go directly from your browser to Salesforce. aprity never sees them.
• The access given to the AI client is limited to your organization's aprity data.
• Your org's login policies apply, and your administrator controls access through your own Connected App.
• Tool calls are logged with your organization's context for audit. Token values are never logged.

See the Security Model for the full aprity authentication and data-handling posture.

Troubleshooting

Symptom	Where to start
Salesforce shows redirect_uri_mismatch at sign-in	The MCP callback URL is missing from the Connected App. See Administrator setup.
Salesforce says the user hasn't approved this app	The user's profile is not among the Connected App's permitted users.
The sign-in fails or loops	MCP authentication failed. Sign in to the org that aprity documents for your organization.
401 Unauthorized on every tool call	Remove the aprity server from the client and add it again to sign in afresh. See MCP authentication failed.
The Connectors card says the MCP URL is not configured	Contact contact@aprity.ai.
Tools are refused after connecting	Check that your plan includes the Remote MCP Server and that the tool-call quota is not used up.
Answers feel out of date	Run a new scan: the AI client only sees the latest successful scan.

For anything else, contact contact@aprity.ai.