Skip to main content

Claude Desktop — Connect to aprity

This guide walks through connecting Claude Desktop (macOS / Windows) to your aprity-scanned Salesforce org. Once connected, Claude can answer questions about your org, describe object behaviour, and draft user stories from your latest aprity scan.

See Remote MCP Server for the feature overview, plan availability and quotas.

aprity's Remote MCP Server is an OAuth 2.1 endpoint at https://mcp.aprity.ai/v1/mcp. You point Claude Desktop at that URL and it walks you through an OAuth 2.1 + PKCE sign-in that authenticates you with Salesforce SSO. There is no token to copy or paste by hand.

Prerequisites​

  • Your aprity tenant is on the Intelligence or Trial plan (the Remote MCP Server is not available on Documentation), with the feature.mcpRemoteServer feature enabled.
  • Claude Desktop installed on macOS or Windows, on a version that supports remote MCP servers over HTTP with OAuth.
  • A Salesforce login for the org that aprity has scanned (you sign in with this during the OAuth flow).

Step 1 — Add the aprity MCP server​

Claude Desktop reads its MCP configuration from a JSON file on disk:

  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows : %APPDATA%\Claude\claude_desktop_config.json

Open (or create) the file and add the aprity entry inside the mcpServers object — just the URL, no token:

{
    "mcpServers": {
        "aprity": {
            "url": "https://mcp.aprity.ai/v1/mcp"
        }
    }
}

If the file already has other MCP servers, keep them and add the aprity entry inside the existing mcpServers object -- do not overwrite the whole file.

Step 2 — Restart Claude Desktop​

Quit Claude Desktop fully and reopen it (Cmd+Q on macOS, fully close on Windows). Claude Desktop only reads the config at startup.

Step 3 — Sign in with Salesforce SSO​

The first time Claude Desktop connects to the aprity server, it opens a browser window for the OAuth 2.1 + PKCE flow:

  1. Sign in with Salesforce SSO -- the same credentials you use for your aprity-scanned org.
  2. aprity resolves your tenant from your Salesforce org.
  3. Approve the connection. Claude Desktop receives a short-lived token automatically; there is nothing to copy or paste.

Verify the connection​

In any conversation, open the tools / connectors panel. You should see the aprity connector with its tools, including:

  • Answer a question -- open-ended Q&A about your org.
  • Describe object behaviour -- triggers, flows, validations, ownership for a given object and event.
  • Draft a user story -- generate a Given/When/Then user story from a free-text intent.

These run on aprity's deterministic knowledge tools over your latest scan. Try a quick sanity check: ask Claude "What does aprity know about my Account object?". The answer should cite specific automations, validations, or fields from your scan.

Disconnect or reconnect​

  • Stop using the connection : remove the aprity entry from claude_desktop_config.json and restart Claude Desktop. The next request can no longer reach aprity.
  • Reconnect : add the entry back and restart; Claude Desktop runs the Salesforce SSO sign-in again.

Disconnect when the device is decommissioned, the connection is no longer needed, or the Salesforce user who authorized it leaves the company.

Limitations specific to Claude Desktop​

  • The claude_desktop_config.json file is per-user, not per-workspace. Each team member adds their own aprity entry and signs in with their own Salesforce identity.
  • Claude Desktop only reads the config at startup -- changes to the file require a full quit + reopen, not just closing the window.
  • The connection is tied to the Salesforce user who signed in via SSO.

Troubleshooting​

SymptomWhere to start
Claude Desktop does not detect the aprity server after editing the configFully quit Claude Desktop (Cmd+Q on macOS) and reopen. The config is only read at startup.
The OAuth sign-in fails or loopsMCP authentication failed. Confirm you sign in with the correct Salesforce identity for your aprity-scanned org.
401 Unauthorized on every tool callMCP authentication failed
Tools missing after the connector loadsConfirm your plan includes the Remote MCP Server. See Plan Comparison.
The "aprity" connector does not appear at allConfirm the JSON file is valid (no trailing commas, correct nesting) and that the URL is exactly https://mcp.aprity.ai/v1/mcp.

For anything else, contact support@aprity.ai.