Skip to main content

Claude Code (CLI) — Connect to aprity

This guide walks through connecting Claude Code, Anthropic's command-line coding agent, to your aprity-scanned Salesforce org. Once connected, Claude Code can answer questions about your org, describe object behaviour, and draft user stories from your latest aprity scan -- directly from your terminal.

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 Code 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 Code installed on macOS, Windows, or Linux, 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 Code reads MCP server definitions from one of two JSON config files, depending on scope:

  • Workspace-scoped (recommended for project-specific tools) : .mcp.json at the root of your project.
  • Global (available across every project) :
    • macOS / Linux : ~/.claude/mcp.json
    • Windows : %USERPROFILE%\.claude\mcp.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.

Because the config holds only the server URL and no secret, it is safe to commit .mcp.json to a shared repository -- each developer signs in with their own Salesforce identity when their session first connects.

Step 2 — Restart your Claude Code session​

Open a fresh terminal and start claude again. Existing sessions do not pick up changes to mcp.json until restart.

Step 3 — Sign in with Salesforce SSO​

The first time your Claude Code session connects to the aprity server, it triggers the OAuth 2.1 + PKCE flow:

  1. Follow the prompt to open the sign-in page in your browser.
  2. Sign in with Salesforce SSO -- the same credentials you use for your aprity-scanned org.
  3. aprity resolves your tenant from your Salesforce org.
  4. Approve the connection. Claude Code receives a short-lived token automatically.

Verify the connection​

In a Claude Code session, ask "What aprity tools are available?". Claude Code lists the aprity tools, including Answer a question, Describe object behaviour, and Draft a user story -- all backed by aprity's deterministic knowledge tools over your latest scan.

Then try a sanity check: "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 mcp.json and start a fresh Claude Code session.
  • Reconnect : add the entry back and start a fresh session; Claude Code 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 Code​

  • The config file is read at session start. Restart your Claude Code session after editing.
  • The connection is tied to the Salesforce user who signed in via SSO.

Troubleshooting​

SymptomWhere to start
Claude Code does not list the aprity toolsRestart the session in a fresh terminal. Confirm the JSON file is valid (no trailing commas).
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 server loadsConfirm your plan includes the Remote MCP Server. See Plan Comparison.

For anything else, contact support@aprity.ai.