Stats
Actions
Tags
'%20stop-opacity%3D'0.16'%2F%3E%3Cstop%20offset%3D'1'%20stop-color%3D'rgb(200%2C90%2C60)'%20stop-opacity%3D'0.03'%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D'320'%20height%3D'200'%20fill%3D'url(%23g)'%2F%3E%3Ccircle%20cx%3D'250'%20cy%3D'56'%20r%3D'92'%20fill%3D'rgb(200%2C90%2C60)'%20fill-opacity%3D'0.06'%2F%3E%3Ccircle%20cx%3D'64'%20cy%3D'172'%20r%3D'58'%20fill%3D'rgb(200%2C90%2C60)'%20fill-opacity%3D'0.05'%2F%3E%3C%2Fsvg%3E)
Salesforce Hosted MCP Server setup, configuration, URL patterns, ECA management, security model, complete tool reference, and troubleshooting
How this skill is triggered — by the user, by Claude, or both
Slash command
/sf-compound-engineering:hosted-mcp-serversThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**SCOPE: HOSTED_MCP** - This skill applies to setting up and configuring Salesforce Hosted MCP Servers.
SCOPE: HOSTED_MCP - This skill applies to setting up and configuring Salesforce Hosted MCP Servers. Use when: Enabling MCP servers in an org, creating External Client Apps, connecting AI clients (Claude, Cursor, ChatGPT), or troubleshooting MCP connectivity.
Salesforce Hosted MCP Servers are fully managed, cloud-hosted MCP (Model Context Protocol) servers that let AI clients access Salesforce data and logic. All processing is deterministic — no LLM runs server-side. Intelligence is entirely on the client side.
This is different from the @salesforce/mcp CLI-based MCP server used for local development.
| Server | API Name | Capabilities | Risk Level |
|---|---|---|---|
| SObject Reads | platform/sobject-reads | Query, search, schema, relationships (read-only) | Lowest |
| SObject Mutations | platform/sobject-mutations | Create + update + query/search (no delete) | Medium |
| SObject All | platform/sobject-all | Full CRUD + query + search + prompt templates | Highest |
| SObject Deletes | platform/sobject-deletes | Delete + query/search for targeting | High |
| Server | Purpose |
|---|---|
| API Catalog | REST API endpoints from Salesforce's API library as tools |
| Custom Servers | User-defined servers with curated tool sets |
| Data 360 | Querying unified customer data |
| Flows | Autolaunched Flows exposed as MCP tools |
| Invocable Actions | @InvocableMethod Apex classes as tools |
| Prompt Builder | Prompt Builder templates as MCP prompts |
| Tableau Next | Semantic model discovery, KPI querying, analytics |
platform/sobject-reads for evaluation — zero data modification riskplatform/sobject-mutations for create/update without delete capabilityplatform/sobject-all for production — includes prompt templatesmcp-tool-builder skill)| Tool | Parameters | Description |
|---|---|---|
getSchema | object-name (optional) | No param: compact object catalog. With param: full field schema with types, required flags, picklist values |
soqlQuery | query (required) | Execute SOQL queries. Always include WHERE and LIMIT |
soslSearch | search (required) | Text search across multiple objects via SOSL |
getAuthenticatedUser | none | User identity: ID, name, email, role, profile, manager, timezone |
getRecentlyViewed | sobject-name (required) | Recently viewed/modified records |
getRelatedRecords | sobject-name, id, relationship-path (all required) | Traverse relationships for child records |
| Tool | Parameters | Description |
|---|---|---|
createSobjectRecord | sobject-name, body (required) | Create new records |
updateSobjectRecord | sobject-name, id, body (required) | Update records by ID |
updateChildRecord | sobject-name, id, relationship-path, body (required) | Update child via relationship |
deleteSobjectRecord | sobject-name, id (required) | Delete record (15-day Recycle Bin recovery) |
deleteChildRecord | sobject-name, id, relationship-path (required) | Delete child via relationship |
| Category | Tools |
|---|---|
| Analytics | analyze_data, list_dashboards, get_dashboard, list_visualizations, get_visualization |
| Schema | list_semantic_models, get_semantic_model, list_data_objects, list_relationships |
| Metrics | list_measures, list_dimensions, list_semantic_model_metrics, get_metric |
| Navigation | list_workspaces, list_workspace_assets, search_assets |
Tableau Next endpoints:
https://api.salesforce.com/platform/mcp/v1/analytics/tableau-nexthttps://api.salesforce.com/platform/mcp/v1/sandbox/analytics/tableau-nextEverything is encoded in the URL path (no query parameters or headers during discovery).
| Org Type | URL Pattern |
|---|---|
| Production | https://api.salesforce.com/platform/mcp/v1/{servername} |
| Sandbox | https://api.salesforce.com/platform/mcp/v1/sandbox/{servername} |
| Scratch Org | https://api.salesforce.com/platform/mcp/v1/sandbox/{servername} |
| Developer Edition | https://api.salesforce.com/platform/mcp/v1/{servername} |
Required for orgs that disabled login from standard endpoints.
| Org Type | URL Pattern |
|---|---|
| Production | https://api.salesforce.com/platform/mcp/v1/d/{mydomainname}/{servername} |
| Sandbox | https://api.salesforce.com/platform/mcp/v1/d/{mydomainname}--{sandboxname}/sandbox/{servername} |
| Scratch Org | https://api.salesforce.com/platform/mcp/v1/d/{mydomainname}/scratch/{servername} |
| Developer Edition | https://api.salesforce.com/platform/mcp/v1/d/{mydomainname}/develop/{servername} |
MCPService permission enabled (auto-enabled for eligible orgs; contact Support if missing)platform/sobject-reads)At GA, all MCP servers are disabled by default. Each must be individually enabled.
mcp_api + refresh_tokenImportant: ECAs may take up to 30 minutes to propagate worldwide. Try after 1-2 minutes first.
Every MCP client needs three values:
Always test with Postman before connecting AI clients — it returns raw JSON without LLM interpretation.
| Scope | Purpose | Required |
|---|---|---|
mcp_api | Access Salesforce hosted MCP servers | Yes |
refresh_token | Maintain persistent sessions | Yes |
Beta scopes are retired. Do not use
api,sfap_api, oreinstein_gpt_api— these were beta-only and will cause 401 errors.
| Change | Beta | GA |
|---|---|---|
| URL version | v1-beta.2 | v1 |
| Scopes | api, sfap_api, refresh_token, einstein_gpt_api | mcp_api, refresh_token |
| Activation | Org-wide toggle | Per-server in Setup (disabled by default) |
| Tokens | Beta tokens invalid | Must reauthorize |
| Client | Callback URL |
|---|---|
| Claude | https://claude.ai/api/mcp/auth_callback |
| Cursor | cursor://anysphere.cursor-mcp/oauth/callback |
| Postman (Desktop) | https://oauth.pstmn.io/v1/callback |
| Postman (Web) | https://oauth.pstmn.io/v1/browser-callback |
| ChatGPT | Copy from ChatGPT Advanced settings — changes between releases |
Create separate ECAs for each MCP client for per-client auditing and revocation.
| Setting | Purpose | When |
|---|---|---|
| Require Client Secret | Prevent unauthorized token requests | Web server apps (Claude, ChatGPT) |
| Permission Set Restriction | Limit to specific user groups | Production orgs |
| IP Restrictions | Restrict to known IP ranges | Fixed-IP clients |
| Token Rotation | Rotate refresh tokens on use | All production |
| Refresh Token Expiry | Expire tokens after 30 days | All production |
| Single Logout | End MCP when SF session ends | Shared workstations |
.well-known discovery: MCP client receives 401 pointing to .well-known endpoint with OAuth metadataThe agent inherits the authenticated user's full security context:
"If you can't do it in the Lightning UI or over the REST API, you can't do it via MCP."
The mcp_api OAuth scope is separate from REST API access. An MCP connection cannot access REST APIs. Full REST API access requires the api scope on a different ECA.
platform/sobject-reads — zero data modification risk"Field labels and descriptions are the primary input the LLM uses to understand your org. If your custom fields have cryptic API names and no descriptions, the agent will struggle."
mcp_api refresh_tokenhttps://login.salesforce.com/services/oauth2/authorizehttps://login.salesforce.com/services/oauth2/tokenhttps://test.salesforce.com/services/oauth2/authorizehttps://test.salesforce.com/services/oauth2/tokenTest with JSON calls:
// Test authentication
{"method": "tools/call", "params": {"name": "getUserInfo", "arguments": {}}}
// Test SOQL
{"method": "tools/call", "params": {"name": "soqlQuery", "arguments": {"query": "SELECT Id, Name FROM Account LIMIT 5"}}}
mcp.json with server URL and consumer key| Symptom | Cause | Resolution |
|---|---|---|
| 404 on MCP URL | Server not activated | Enable in Setup > API Catalog > MCP Servers; wait 2 minutes |
| 401 Unauthorized | Wrong OAuth scopes | Verify ECA has mcp_api + refresh_token (not beta scopes) |
| 401 persistent | ECA not propagated | Wait up to 30 minutes after ECA creation |
| 403 Forbidden | Insufficient permissions | Check user's profile, permission sets, and sharing rules |
| Wrong data returned | Environment mismatch | Don't mix Production and Sandbox URLs |
| Connection refused | Edition requirement | Verify Enterprise+ or Developer Edition |
| "Failed to attach prompt" | Flow in templateDataProviders | Remove templateDataProviders with flow:// references for MCP |
| Prompt format ignored | Claude doesn't enforce templates | Pre-format output server-side or embed format in tool description |
| Client | Issue | Fix |
|---|---|---|
| Cursor | MCP process hangs | Force quit and restart Cursor |
| Cursor | Server not responding | Toggle off/on with 1-2 min wait |
| ChatGPT | Callback URL invalid | Re-copy from ChatGPT Advanced settings (changes between releases) |
| ChatGPT | Salesforce not in chat | Must explicitly select via + button |
| Claude | Connector issues | Admin Settings > Connectors to manage |
| Postman | STDIO mode selected | Switch to HTTP mode |
| Tableau Next | Slow responses in Claude | ~1 min response time; Agentforce is 10-20x faster |
| Limitation | Detail |
|---|---|
| Edition requirement | Enterprise Edition or above (Developer Edition also qualifies) |
| ECA propagation | Up to 30 minutes after creation or modification |
| Server activation | Up to 2 minutes after toggling on/off |
| Experience Cloud URLs | Not supported (planned for future) |
| API quota | MCP tool calls consume daily API quota |
mcp-remote npm | Not supported — only native OAuth/HTTP MCP clients work |
| No DCR | Dynamic Client Registration not supported |
| No undelete | Deleted records go to Recycle Bin but no MCP undelete tool |
| Scratch Org ECAs | Cannot create via Setup UI — must package from DevHub |
| Connected Apps | Not supported for MCP — must use External Client Apps |
| Prompt templates | Only Flex/Global templates. ChatGPT does NOT support MCP prompts |
| ISV packaging | Managed packages cannot include MCP server configs — expose via annotated Apex/Flows for subscribers to configure |
ECAs cannot be created directly in scratch orgs:
Third-party gateways for centralized governance across multiple MCP servers:
These provide: approved server registry, centralized access controls, advanced audit trails, compliance solutions.
| Aspect | Hosted MCP Servers | Salesforce DX MCP (@salesforce/mcp) |
|---|---|---|
| Hosting | Cloud-managed by Salesforce | Local CLI on developer machine |
| Audience | End users, AI agents, production workflows | Developers during local development |
| Transport | Streamable HTTP via api.salesforce.com | STDIO via npx CLI |
| Auth | OAuth 2.0 + PKCE via External Client Apps | SF CLI authentication (sf org login) |
| Tools | SObject CRUD, prompt templates, custom actions | 60+ dev tools: deploy, retrieve, test, analyze |
| Use Case | AI clients querying CRM data in production | Claude Code building/deploying Salesforce code |
| Configuration | Per-org in Setup > API Catalog | Per-project in .mcp.json |
platform/sobject-reads, risk-free, use Postman alongsideplatform/sobject-all or custom servers with selective writesnpx claudepluginhub gellasangameshgupta/salesforce-compound-engineering-plugin --plugin sf-compound-engineeringCreates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.