CRM Analytics MCP Server (Beta)
CRM Analytics MCP server is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer’s sole discretion.
Important
The crma-beta server gives AI agents direct, read-only access to CRM Analytics without any custom integration. With a single OAuth connection, agents like Claude, Cursor, ChatGPT, and Agentforce Vibes 2.0 can discover your analytics apps, inspect dataset schemas, run Salesforce Analytics Query Language (SAQL) queries, and read dashboard and lens metadata.
When an agent queries through this server, it first inspects a dataset’s schema through its extended metadata (XMD) to generate accurate SAQL queries with the correct syntax and field API names. Because the server handles schema resolution automatically, users get accurate results without needing to know SAQL syntax or field API names themselves. For details on how dataset structure and formatting are defined, see the Salesforce Analytics Extended Metadata (XMD) Developer Guide.
Why Use CRM Analytics MCP Server?
Using CRM Analytics MCP provides several key benefits:
-
Natural-Language Data Access: Business users can ask questions like “What were our top 10 accounts by revenue last quarter?” and get formatted results, without writing SAQL or knowing the underlying dataset schema.
-
Automated Analytics Workflows: Developers building internal reporting tools can pull dataset schemas and query results programmatically, without hard-coding SAQL or managing authentication themselves.
-
Complete Asset Visibility for Admins: Admins can inventory every app, dataset, and dashboard across the org in minutes, building a complete analytics catalog for governance and auditing.
FAQs
Common questions about CRM Analytics MCP server and the Model Context Protocol.
What's MCP?
The Model Context Protocol (MCP) is an open standard that enables AI models to securely access data, tools, and context from specialized systems. CRM Analytics MCP server uses the protocol to expose CRM Analytics datasets, folders, dashboards, and lenses to external AI agents.
Is CRM Analytics MCP Server secure?
Yes. Every request is enforced against the connecting user’s own Salesforce permissions: field-level security, object-level security, row-level security, and sharing rules. Your agent can never see data or assets that you can’t see in CRM Analytics directly. Authentication uses individual OAuth 2.0 and PKCE. Shared service account tokens aren’t supported.
How does CRM Analytics MCP Server generate SAQL queries?
Your agent doesn’t write SAQL blind. The typical workflow is:
list_datasets→get_dataset- to capture the dataset’scurrentVersionIdget_xmd- to get exact field API names, types, and labelsexecute_query- to run the generated SAQL and return structured results
Because the agent inspects the real schema before generating a query, it produces syntactically correct SAQL without you needing to know the dataset’s field names in advance.
Is CRM Analytics MCP Server available in production?
Yes, the CRM Analytics MCP server is available in production, as well as on sandbox and scratch orgs.
To use it, you also need a CRM Analytics license, System Admin permissions to create the external client app and enable the server, and a supported MCP Client. Supported clients include Agentforce Vibes 2.0, Claude (Desktop, Web, Code), Cursor, ChatGPT developer mode, or any client supporting OAuth 2.0 and PKCE.
All CRM Analytics tools are currently read-only.
Server URL
Use these server URLs to access the production and sandbox versions of the MCP server.
- Production: https://api.salesforce.com/platform/mcp/v1/analytics/crma-beta
- Sandbox/Scratch: https://api.salesforce.com/platform/mcp/v1/sandbox/analytics/crma-beta
Example Prompts
- “What analytics apps do I have access to?”
- “What CRM Analytics datasets do I have access to right now?”
- “Give me the full metadata for the Executive Pipeline dataset.”
- “What are the exact fields, dimensions, and measures in the Opportunity dataset?”
- “What were our top 10 accounts by revenue last fiscal year?”
- “What was the total pipeline by region last quarter?”
- “Show me rep performance versus quota this month.”
- “Show me all the dashboards in my Sales Application folder.”
- “List all the saved explorations I’m permitted to view.”
Available Tools
The CRM Analytics MCP server provides a suite of read-only tools that allow external AI agents to interact with your CRM Analytics assets. After you complete the initial setup, you no longer need to manually select or configure these tools. Ask your preferred MCP-compliant AI client, such as ChatGPT, Claude, or Cursor, questions using natural language, and it automatically selects the right tools for the task.
For example, when you ask, “What were our top 10 accounts by revenue last quarter?”, the AI agent calls list_datasets, get_dataset, and get_xmd to understand the data structure, generates valid SAQL, and executes it via execute_query.
The available tools are grouped by their functional role within an analytical workflow.
Organization and Discovery Tools
External MCP-compliant AI agents use these tools to navigate CRM Analytics folders before scoping deeper searches. Folders represent analytics apps.
list_folders
Returns all analytics apps that the connected user can access. Analytics apps or folders are containers for related dashboards, datasets, and lenses. Use the returned ID to scope other list_ calls.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | No | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token. |
scope | enum | No | Filter by scope: CreatedByMe, Mru, SharedWithMe. |
sort | enum | No | Sort order: Name, Mru, LastModified, LastModifiedBy. |
isPinned | boolean | No | When true, returns only pinned folders. |
pageSize | integer | No | Number of results per page. Min: 1, Max: 200, Default: 25. |
page | string | No | Pagination token for the next page of results. |
Outputs: A collection of folder objects, each with ID, label, description, template source, and permissions.
get_folder
Returns full metadata for a single analytics app by ID, including its label, description, template source, and permissions.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
folderId | string | Yes | The ID of the folder to retrieve. Discovered automatically via list_folders. |
Outputs: A folder object with full metadata including label, description, template source, and permissions.
Data and Schema Tools
External MCP-compliant AI agents use these tools to discover datasets and inspect their schemas before building queries.
list_datasets
Returns datasets available in a specific app or across the org, with names, IDs, and last-modified dates.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | No | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token. |
folderId | string | No | Filters results to datasets within a specific folder (app). |
datasetTypes | string | No | Filter by dataset type: Default, Live, StagedData, Trended. |
scope | enum | No | Filter by scope: CreatedByMe, Mru, SharedWithMe. |
sort | enum | No | Sort order: Name, Mru, LastModified, TotalRows, CreatedDate, LastRefreshed, CreatedBy, LastQueried, ConnectionName. |
order | enum | No | Sort direction: Ascending, Descending. |
includeCurrentVersion | boolean | No | When true, includes current version metadata in the response. |
pageSize | integer | No | Number of results per page. Min: 1, Max: 200, Default: 25. |
page | string | No | Pagination token for the next page of results. |
Outputs: A collection of dataset objects with names, types, and last-modified dates.
get_dataset
Returns full metadata for a dataset, including field names, data types, and labels for dimensions and measures. Use this to capture the dataset’s currentVersionId, which get_xmd and execute_query require.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
datasetIdOrApiName | string | Yes | The ID or API name of the dataset. |
Outputs: Full dataset metadata including field names, data types, dimension and measure labels, and current version information.
get_xmd
Returns the extended metadata (XMD) field schema for a dataset version, including exact field API names, data types, labels, and formatting. Use this after get_dataset to get the precise field names an agent needs to build valid SAQL.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
datasetIdOrApiName | string | Yes | The ID or API name of the dataset. |
versionId | string | Yes | 18-character version ID starting with 0Fc (from get_dataset). |
xmdType | enum | No | main (default, query-ready), system, or user. |
Outputs: Extended metadata for the dataset version, including field API names, data types, labels, and display formatting.
Query and Analysis Tools
External MCP-compliant AI agents use this tool to execute analytical queries once they understand the dataset schema.
execute_query
Executes a SAQL query against a CRM Analytics dataset and returns structured results. The AI agent generates SAQL automatically from the natural-language request, using the schema returned by get_dataset and get_xmd.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | SAQL pipeline; the load stage must use "<datasetId>/<currentVersionId>"; end with q = limit q N;. |
queryLanguage | enum | No | Locked to Saql. |
timezone | string | No | IANA timezone, for example America/Los_Angeles. |
version | number | No | SAQL version; omit for latest. |
Outputs: Structured JSON query results containing rows, column metadata, and query execution details.
Dashboard, Visualization, and Exploration Tools
External MCP-compliant AI agents use these tools to discover and inspect prebuilt dashboards and saved explorations (lenses).
list_dashboards
Returns all CRM Analytics dashboards in a specified app or across the org, with names, IDs, and app context.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | No | Search terms. A wildcard is automatically appended to the last token. |
folderId | string | No | Filters results to dashboards within a specific folder (app). |
type | enum | No | Asset type filter. Defaults to Dashboard. Other values: DashboardSnapshot, Component. Component requires edit access and may return no results for view-only users. |
templateApiName | string | No | Filters results to dashboards created from a specific application template. |
mobileOnly | boolean | No | When true, returns only dashboards enabled for the Analytics mobile app. |
ids | string | No | Filters results to only the dashboards with the specified IDs. |
scope | enum | No | Filter by scope: CreatedByMe, SharedWithMe, Mru. |
sort | enum | No | Sort order: Name, Mru, LastModified, LastModifiedBy. |
pageSize | integer | No | Number of results per page. Min: 1, Max: 200, Default: 25. |
page | string | No | Pagination token for the next page of results. |
Outputs: A collection of dashboard objects with names, IDs, types, and app context.
get_dashboard
Returns full metadata for a single dashboard, including widgets, steps, and filter configurations.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
dashboardIdOrApiName | string | Yes | The ID or API name of the dashboard. |
Outputs: Full dashboard metadata including widgets, steps, filter configurations, and layout details.
list_lenses
Returns all saved explorations (lenses) that the connected user can access, with names, IDs, and the datasets they reference.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | No | Search terms. A wildcard is automatically appended to the last token. |
folderId | string | No | Filters results to lenses within a specific folder (app). |
scope | enum | No | Filter by scope: CreatedByMe, SharedWithMe, Mru. |
sort | enum | No | Sort order: Name, Mru, LastModified, LastModifiedBy. |
pageSize | integer | No | Number of results per page. Min: 1, Max: 200, Default: 25. |
page | string | No | Pagination token for the next page of results. |
Outputs: A collection of lens objects with names, IDs, and the datasets they reference.
get_lens
Returns full metadata for a single lens, including the query definition and dataset reference.
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
lensIdOrApiName | string | Yes | The ID or API name of the lens. |
Outputs: Full lens metadata including the query definition, visualization configuration, and dataset reference.
Troubleshooting and Tips for Success
Use these solutions to resolve common issues and optimize the performance of CRM Analytics MCP server across different AI clients.
General Connectivity Issues
Server Connection Fails: Verify you’ve created an external client app using OAuth 2.0 and PKCE, and that an administrator has enabled CRM Analytics MCP server in Setup (MCP Servers under API Catalog). Both steps are required before any client can connect.
Multitenant Conflicts: Because the MCP specification doesn’t support multitenant systems like Salesforce, log out of all other Salesforce orgs, log into the target org in your default browser, and keep that browser window open before connecting your client. The client opens a new tab in that same window during authentication. Most connection failures trace back to skipping this step.
Optimization for AI Clients
Describe Your Goal, Not the Tool: Say “Show me open opportunities by stage” rather than “call list_datasets.” The AI agent handles tool selection.
Improve Query Accuracy with Field Descriptions: Adding field labels and descriptions to your dataset XMD helps your AI agent generate more accurate SAQL queries.
Complex Queries Sometimes Need Refinement: Nested groupings, multi-dataset joins, or advanced SAQL functions can require follow-up prompting to get the exact result you need.
Data and Tool Access
Read-Only During the Beta Program: Create, update, and delete operations aren’t supported yet. If an agent suggests it modified a dataset or dashboard, it didn’t. Treat any such claim as an error.
Missing or Unavailable Assets: If the agent reports that a dataset, dashboard, or lens is unavailable, or a list_ call returns fewer items than you expect, this means you lack permission to that specific asset, not that the server failed. Confirm the app or asset is shared with you and that your permission set grants CRM Analytics access.
Permissions and Governance: MCP sessions use OAuth-authenticated users, meaning any permissions or restrictions that apply to your user profile also apply to your MCP session. Individual authentication is required. Shared service account tokens aren’t supported.
Monitor API Usage: MCP tool calls count against your org’s Wave API limits. Check usage in Setup → API Usage, especially for high-volume workloads.
j