Use the Sigma MCP server

The Sigma MCP server allows you to use natural language to interact programmatically with your Sigma organization using Model Context Protocol (MCP) tools. AI assistants like Claude, ChatGPT, Codex, Cortex Code, and Cursor can use these tools to search, describe, and query data in Sigma, and to build workbooks.

You can use the Sigma MCP server to locate data sources in your organization, explore and describe their contents, analyze your data, and save your analysis as a workbook without leaving the AI assistant’s interface. For example, you can ask your AI assistant to find Sigma documents related to a specific topic, query the data in those documents to uncover insights, and then build a workbook to share those insights.

User requirements

• You must be assigned a Sigma account type with the Use Sigma MCP with OAuth permission enabled.

• You must be assigned a Sigma account type with the permissions to perform the same operation in the Sigma UI:

  • Depending on the type of data source you want to use, you need the View connections, View data models, and/or View workbooks permissions enabled on your account type.
  • To search, explore, or query a specific document, you must be granted at least Can view access to the document.
  • To search, explore, or query a specific connection, you must be granted at least Can use access to the connection.
  • To call agents, you must be granted at least Can view access to a workbook that contains the agent.
  • To build workbooks, you must be assigned an account type with the Create, edit, and publish workbooks and Create, edit, and publish workbooks with Sigma MCP permissions enabled.
    • To edit an existing workbook, you must also be granted Can edit access to the workbook.
  • To take a screenshot of a workbook page or element, you must be assigned an account type with the Create, edit, and publish workbooks with Sigma MCP permission enabled and be granted at least Can view access to the workbook.

• If your organization has an IP allowlist enabled, you must allowlist the IP addresses your AI assistant uses for outbound connections, with a Scope set to API. For Claude, see the Anthropic documentation on IP addresses for the list of required IP addresses. For other AI assistants, consult the documentation for that AI assistant.

Prerequisites

You need your Sigma MCP server URL to configure the Sigma MCP server with an AI assistant.

To find your Sigma MCP server URL:

1. In Sigma, select the user icon (usually composed of your initials), then select Profile.
2. Select Integrations.
3. Under the Connect Sigma to AI tools section, copy the Sigma MCP URL.

Set up the Sigma MCP server in an AI assistant

You can connect to the Sigma MCP server from any AI assistant that supports connection to custom remote MCP servers via HTTP and OAuth. Configuration steps for the Sigma MCP server vary depending on the AI assistant you’re configuring it with. Provide the following information when configuring the Sigma MCP server with an AI assistant:

For configuration steps and requirements to connect an MCP server to other AI assistants, consult the documentation for that AI assistant. Setup instructions for some AI assistants are provided below:

• Claude
• ChatGPT
• Codex
• Cortex Code
• Cursor

Set up the Sigma MCP server in Claude

Search for and connect to the Sigma connector in Claude’s Connectors Directory.

If you’re prompted for a Server URL, use the Sigma MCP URL you retrieved in Prerequisites.

After you select Connect, you’re prompted to authenticate to your Sigma organization and authorize Claude.

If you are an Owner/Primary Owner in Claude for an organization on a Team/Enterprise plan, you can add the Sigma MCP Server as a connector for your organization. Individual users in your organization can then choose to connect and authenticate to the Sigma MCP server when using Claude. See the Claude documentation on Connect a service on Team and Enterprise plans for more information.

Set up the Sigma MCP server in ChatGPT

Sigma is available as a plugin in the ChatGPT plugin marketplace, so you don’t need to configure the Sigma MCP server manually. See Use the Sigma plugin for ChatGPT.

Set up the Sigma MCP server in Codex

You can use the codex mcp add command to add the Sigma MCP server to Codex from the command line. For example:

codex mcp add sigma --url <Sigma MCP URL>

After configuring the MCP server successfully, you’re prompted to authenticate to your Sigma organization and authorize Codex.

For more information, see the OpenAI documentation on Connect Codex to an MCP server.

To connect to the official Sigma plugin for ChatGPT, which packages the Sigma MCP server with a set of skills maintained by Sigma, follow the steps to install the Sigma plugin for ChatGPT.

Set up the Sigma MCP server in Cortex Code

You can use the cortex mcp add command to add the Sigma MCP server to Cortex Code from the command line. For example:

cortex mcp add sigma <Sigma MCP URL> --transport http

After configuring the MCP server successfully, you’re prompted to authenticate to your Sigma organization and authorize Cortex Code.

For more information, see the Cortex Code documentation on Adding a server.

Set up the Sigma MCP server in Cursor

You can configure custom MCP servers in Cursor by editing your mcp.json file. In your Cursor MCP settings, add a new custom MCP server using the following template:

{
  "mcpServers": {
    "sigma": {
      "url": "<Sigma MCP URL>"
    }
  }
}

After editing the mcp.json file, navigate back to your settings and connect the MCP server. You’re prompted to authenticate to your Sigma organization and authorize Cursor.

For more information about configuring custom MCP servers in Cursor, see the Cursor documentation on Installing MCP servers.

Authentication

The Sigma MCP server authenticates to Sigma using OAuth. Permissions are inherited from your existing Sigma account. No additional configuration is required besides logging into your Sigma account when prompted. Your Sigma login method doesn’t affect how your AI assistant authenticates. Sigma handles authentication to the MCP server automatically for all users with accounts in Sigma.

Features

The Sigma MCP server supports several features for interacting with Sigma using natural language, including:

• Searching for data in your organization
• Exploring data sources and their contents
• Analyzing your data
• Building workbooks
• Taking screenshots of workbooks
• Calling Sigma agents

Searching for data

Search your entire Sigma organization for documents and data sources, including data models, warehouse tables, and elements from workbooks and data models. Search by criteria like document name, type, owner, and connection. Browse and list collections of documents, helping you to quickly locate documents across large organizations.

Example prompts include:

• “Does the DECEMBER_SALES table exist in the Sample Data connection in Sigma?”
• “Find all reports created in Sigma by Dana Lee.”
• “Are there any workbooks or data models in Sigma on revenue for FY24 Q3?”

Exploring data sources and documents

Explore data sources and documents in Sigma by asking questions about column names, definitions, and descriptions. Check structure, data types, and column attributes to confirm the source meets your analytics needs.

Example prompts include:

• “What columns are available in the CUSTOMER_CALLS table in Sigma?”
• “What geographical data is available in the APAC Stores data model in Sigma?”
• “What is the primary key of the EMPLOYEES table of the HR data model in Sigma?”

Analyzing your data

Ask about data in your connections, data models, or workbooks, without needing to write SQL. Ask follow-up questions to further refine your analysis.

Example prompts include:

• “Use Sigma to find the top 10 sales representatives with the most deals closed in FY25.”
• “Use Sigma to summarize customer calls with CorporationX over the last 30 days.”
• “Use Sigma to find customer accounts with unresolved support tickets and a renewal date in the next 30 days.”

Building workbooks

Describe the workbook you want, and your AI assistant builds it in Sigma. After locating and exploring a data source, your AI assistant creates the workbook based on your description. When it’s done, your AI assistant returns a link to the workbook so you can review it and continue building in Sigma. You can also ask your AI assistant to edit an existing workbook that you have access to edit.

Sigma saves new workbooks in the Your documents folder. When your AI tool edits an existing workbook, Sigma publishes a new version of the workbook.

Example prompts include:

• “Build a Sigma workbook that tracks monthly sales by region from the Sales data model.”
• “In Sigma, create a workbook with a bar chart of the top 10 customers by revenue.”
• “Add a page to the Regional Sales workbook in Sigma with a KPI for year-over-year growth.”

Taking screenshots of workbooks

Ask for a screenshot of a workbook page or element to see it in the chat. Your AI assistant can also take screenshots to review the workbooks it builds.

Example prompts include:

• “Show me a screenshot of the Overview page of the Regional Sales workbook in Sigma.”
• “Take a screenshot of the revenue trend chart in the Q3 Forecasting workbook in Sigma.”

Calling Sigma agents

List the Sigma agents available in a workbook and chat with a specific agent to accomplish a task, such as forecasting or summarizing data. When you run a Sigma agent from the Sigma MCP server, your AI tool can prompt the agent to use tools on your behalf. For example, if you have a project tracking agent set up with an action tool to update an input table with project status updates, you can prompt that agent to add a new project status update using details from the conversation in your AI tool.

This functionality is only available through the Sigma MCP server, not the Sigma plugin for ChatGPT and Codex.

Example prompts include:

• “What Sigma agents are available in the Q3 Forecasting workbook?”
• “Ask the sales copilot agent in Sigma to summarize this quarter’s at-risk accounts.”
• “Use the sales copilot agent in Sigma to update the account status and notify Bob.”

Usage examples

Example 1: Find relevant documents

You can use the Sigma MCP server to find documents relevant to your analysis. For example, with the following prompt:

The following occurs:

1. The AI tool searches across your Sigma organization for workbooks, data models, and tables that are related to regional sales performance. The AI tool returns the names of relevant documents.
2. You can ask additional questions to learn more about specific data sources, or to analyze the data.

Example 2: Explore data sources

You can use the Sigma MCP server to explore data sources in Sigma. For example, with the following prompt:

The following occurs:

1. The AI tool searches across your Sigma organization for the F_SALES table.
2. The AI tool returns the column names and data types of all the columns in the table.
3. You can ask additional questions to learn more about specific columns, or to query the data.

Example 3: Answer data questions

You can use the Sigma MCP server to answer specific data questions in Sigma. For example, with the following prompt:

The following occurs:

1. The AI tool searches across your Sigma organization for relevant documents and elements and locates a relevant data source.
2. The AI tool describes the data source and locates relevant sales and store location columns.
3. The AI tool queries the data to find stores that meet the listed criteria and returns the results.

Example 4: Build a workbook

You can use the Sigma MCP server to save your analysis as a workbook. For example, with the following prompt:

The following occurs:

1. The AI tool searches across your Sigma organization for relevant documents and elements and locates a relevant data source.
2. The AI tool describes the data source and queries the data to confirm the relevant sales and store location columns.
3. The AI tool creates a workbook in the Your documents folder and returns a link to the workbook.
4. You can ask the AI tool for a screenshot of the workbook, request changes, or open the workbook in Sigma to continue building.

Monitor MCP queries

You can use the "kind":"mcp" tag to monitor queries sent by the Sigma MCP server. For example, you might want to configure query tags in your data platform to monitor costs associated with MCP server queries. See the Snowflake documentation on QUERY_TAG, the Databricks documentation on Query tags, or the documentation for your specific data platform for more information.

Troubleshooting and notes

This section provides details about limitations and some known configuration errors. If you encounter an issue that is not included below, contact Support.

Limitations

• If you do not have an AI provider enabled for your organization, search returns less relevant results. To improve the quality of search results, enable an AI provider. See Configure AI features for your organization. All tools function without an AI provider.
• Avoid using queries that include custom window frames, ordered window aggregates, and dynamic intervals. These queries are not currently supported.
• The Sigma MCP server only queries the published version of a document. If you have access to a tagged version of a document but not to its published version, queries against that document fail with a permission error.
• The Sigma MCP server cannot create workbooks in a shared folder, even if you have Can edit access to the folder. Sigma saves new workbooks in the Your documents folder.
• Screenshots capture a single workbook page or element. To capture an entire workbook, request a screenshot of each page.
• Screenshots count toward the rate limit on the Sigma API export endpoints, which is 400 requests per minute. If a screenshot takes longer than 10 minutes to generate, the request fails.
• The following limitations apply when building a workbook with the Sigma MCP server:
  • The Sigma MCP server cannot create workbooks that contain AI columns.
  • The Sigma MCP server cannot create workbooks that contain custom SQL elements. Elements built with the Sigma MCP server must use existing data sources, such as tables, data models, or other data elements.
  • To add an image to a workbook, provide a publicly accessible image URL. The Sigma MCP server cannot add images that you upload or attach to your conversation.
  • Input tables that write data to your data platform require a connection with write access enabled. If the connection doesn’t support write access, requests to create those input tables fail.

Permission errors when building workbooks

If your account type does not have the permissions required to build workbooks, requests to build a workbook fail with an error. For example:

Creating a Sigma workbook requires a Build license or higher. Your Sigma admin must upgrade your account to use this tool.

To resolve this, ask your Sigma admin to assign you an account type with the permissions listed in User requirements.

Missing tools or “tool not found” errors

AI assistants save the list of tools the Sigma MCP server provides. If your permissions change, or Sigma adds new tools, your AI assistant might not list the tools or might return a tool not found error.

To resolve this, refresh the tool list for the Sigma MCP server in your AI assistant’s settings. If your AI assistant doesn’t offer a refresh option, disconnect and reconnect the Sigma MCP server.

URL issues

If you are not using the correct MCP URL in your configuration, you might encounter the following error:

Couldn't reach the MCP server. You can check the server URL and verify if the server is running.

To resolve this, ensure you are using the correct Sigma MCP URL. The URL can be found in Profile > Integrations > Connect Sigma to AI tools. Use the exact Sigma MCP URL listed when configuring the MCP server.

Privacy policy

For more information, see the Sigma Privacy Notice.

Support

Contact Sigma support for additional assistance.