> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/connect-your-platform/snowflake-cowork.md). # Snowflake CoWork [Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors) connects to CARTO through an **external MCP server** configured as an MCP Connector. You can create the connector from the Snowflake UI or with SQL. Once configured, the connector can be added to a **Cortex Agent**. Snowflake also supports MCP Connectors in [Snowflake CoWork](https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-cowork/integrate-tools). {% hint style="info" %} CoWork is Snowflake's chat surface, where CARTO is reached through an agent you create and publish. For [Snowflake CoCo](/carto-for-agents/connect-your-platform/snowflake-coco.md), the coding agent, CARTO is configured differently: MCP, the CARTO CLI and the Agent Skills all apply there. {% endhint %} ## Requirements Before you start, you need: * **ACCOUNTADMIN** access to the Snowflake account. * Your CARTO **MCP Server URL**. You also need a **CARTO SPA OAuth Client**. The client must be **confidential** and have a **Client Secret**. Snowflake does not support public or PKCE-only clients for this integration, and static API tokens are not supported. ## Connect via OAuth OAuth is the authentication method used for the CARTO MCP connection. ### 1. Create a CARTO SPA OAuth Client In CARTO, create a **SPA OAuth Client** under **Developers > Credentials > SPA OAuth Clients**. * Configure the client as **confidential** so that it has a **Client Secret**. * Keep the **Client ID** and **Client Secret**. You will need them when configuring the Snowflake MCP Connector. Before continuing, register Snowflake's OAuth callback URL with the client. In the SPA OAuth Client, disable **Use default logout/callback URLs and Origins** and add: ``` https://identity.snowflake.com/oauth2/callback ``` ### 2. Create the MCP Connector You can create the connector from the [Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors) UI or with SQL. Both create the same Snowflake objects. #### Snowflake UI Go to **Settings > MCP connectors > Add MCP Connector**
Fill in:
FieldValue
LocationA real database and schema.
NameAnything, for example carto_mcp_server
DescriptionWhat the connector is for. Snowflake shows this to the agent
API IntegrationStandard OAuth
Server URLYour MCP Server URL
Authorization endpointhttps://auth.carto.com/authorize
Token endpointhttps://auth.carto.com/oauth/token
OAuth Client ID/SecretFrom your SPA client
Scopesopenid,profile,email,read:workflows,write:workflows
{% hint style="info" %} Do not use the **Dynamic Client Registration (DCR)** tab. Select **Standard OAuth** and enter the CARTO OAuth credentials manually. For more information, see [Snowflake's MCP Connector documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors). {% endhint %} #### SQL Run the following as **ACCOUNTADMIN**. Create the API Integration: ```sql CREATE API INTEGRATION CARTO_MCP_OAUTH2 API_PROVIDER = external_mcp API_ALLOWED_PREFIXES = ('https://.api.carto.com') API_USER_AUTHENTICATION = ( TYPE = OAUTH2 OAUTH_GRANT = AUTHORIZATION_CODE OAUTH_CLIENT_ID = '' OAUTH_CLIENT_SECRET = '' OAUTH_TOKEN_ENDPOINT = 'https://auth.carto.com/oauth/token' OAUTH_AUTHORIZATION_ENDPOINT = 'https://auth.carto.com/authorize' OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_BASIC OAUTH_ALLOWED_SCOPES = ('openid','profile','email','read:workflows','write:workflows')) ENABLED = TRUE; ``` Then create the external MCP server: ```sql CREATE EXTERNAL MCP SERVER CARTO_MCP_SERVER WITH DISPLAY_NAME = 'CARTO MCP' URL = 'https://.api.carto.com/mcp/' API_INTEGRATION = CARTO_MCP_OAUTH2; ``` {% hint style="info" %} Replace `` and `` with the values from your CARTO MCP Server URL. `OAUTH_GRANT = AUTHORIZATION_CODE` is required for this configuration because the CARTO SPA client uses the authorization-code flow. `CREATE OR REPLACE` is not supported for this API integration type. To change the integration, drop it and create it again. {% endhint %} ### 3. Grant access The role that creates and uses the agent needs `USAGE` on the following objects: * the **API integration** * the **external MCP server** * the **database** * the **schema** If you created the connector in the UI, use the following command to find the generated objects: ```sql SHOW EXTERNAL MCP SERVERS; ``` Then, as **ACCOUNTADMIN**, grant access to the role used by the agent: ```sql GRANT USAGE ON INTEGRATION CARTO_MCP_OAUTH2 TO ROLE ; GRANT USAGE ON EXTERNAL MCP SERVER CARTO_MCP_SERVER TO ROLE ; GRANT USAGE ON DATABASE TO ROLE ; GRANT USAGE ON SCHEMA . TO ROLE ; ``` You can also manage access to the agent from its **Access** tab. See [Snowflake's MCP Connector documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors) for more information about permissions. ### 4. Add the MCP Connector to an Agent In the Snowflake UI, go to: **Agents > open your agent > Configuration > MCP > Add to agent** Select the CARTO MCP Connector and complete the **Connect** consent flow. This signs you in to CARTO and authorizes the connection. For the full agent configuration flow, see [Snowflake's Cortex Agents documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents) ### 5. Add the CARTO Agent Skills This step is optional. [CARTO Agent Skills](/carto-for-agents/agent-skills.md) are playbooks that teach an agent to drive CARTO idiomatically, and Snowflake agents can load them from a Git repository. The catalog is public, so no credentials are required. Run the following as **ACCOUNTADMIN**: ```sql CREATE OR REPLACE API INTEGRATION github_cartodb API_PROVIDER = git_https_api API_ALLOWED_PREFIXES = ('https://github.com/CartoDB') ENABLED = TRUE; CREATE OR REPLACE GIT REPOSITORY ..carto_agent_skills API_INTEGRATION = github_cartodb ORIGIN = 'https://github.com/CartoDB/agent-skills'; ALTER GIT REPOSITORY ..carto_agent_skills FETCH; GRANT READ ON GIT REPOSITORY ..carto_agent_skills TO ROLE ; ``` Then, in the agent's **Configuration > Skills > Add skill**, point at a skill folder in the repository: ``` @..carto_agent_skills/branches/master/skills/carto-create-builder-maps ``` {% hint style="info" %} Skills are added one at a time. There is no way to attach the whole catalog at once, so start with `carto-create-builder-maps` and `carto-basics`. A Git repository is an internal stage, so it requires `GRANT READ` rather than `GRANT USAGE`. {% endhint %} ### 6. Publish the agent to Snowflake CoWork The agent is available in [Snowflake CoWork](https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-cowork/integrate-tools) once it is published and added to CoWork. 1. Select **Save**, then **Publish**. A draft agent does not appear in CoWork. 2. Next to the agent name, open the **⋮** menu and select **Add to Snowflake CoWork**. 3. In Snowflake CoWork, go to **Capabilities > MCP Connectors** and select **Connect** on the CARTO connector. This completes the OAuth consent and signs you in to CARTO. Each person who uses the agent does this once. 4. Start a **New chat** and select the agent. {% hint style="info" %} Access is per user. Each person authorizes with their own CARTO account, and the agent inherits that account's CARTO permissions: the connections, maps and workflows that account can reach. {% endhint %} ### 7. Test the connection Snowflake can create the API integration and external MCP server even if the OAuth credentials are invalid. The integration may appear healthy until the agent actually connects to CARTO. **Always run the agent before considering the setup complete.** Ask the agent to use a CARTO tool or describe the tools available to it. If you see an error such as: ``` Insufficient privileges to operate on Integration ``` check the `USAGE` grants on the API integration and external MCP server. For information about MCP tools and how clients discover and invoke them, see the [MCP Tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools). {% hint style="info" %} Maps do not render inside Snowflake. Inline rendering requires MCP Apps support, which is available on [a subset of platforms](/carto-for-agents/connect-your-platform.md#which-platforms-render-maps-inline). The agent creates the map and returns its URL, which you open in CARTO Builder. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.carto.com/carto-for-agents/connect-your-platform/snowflake-cowork.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.