Snowflake Setup Guide

This guide walks you through connecting Carbon Arc's MCP Server to Snowflake Cortex Agents and Snowflake CoWork (formerly Snowflake Intelligence). Once connected, your Cortex Agents and CoWork users can query Carbon Arc's alternative data in natural language, directly inside Snowflake's governed environment. Your users authenticate with their own Carbon Arc credentials via OAuth, so access stays governed by your Carbon Arc subscription and entitlements.

Requirements

A Snowflake account with access to Cortex Agents and MCP Connectors
A role with ACCOUNTADMIN privileges, or CREATE EXTERNAL MCP SERVER on the target schema plus rights to create API integrations (by default, only account admins hold these privileges)
A Carbon Arc platform account for each user who will query the data — any Carbon Arc user can connect, as long as they also have access to the Snowflake account. Don't have an account yet? Follow the Account Setup guide to sign up

Carbon Arc MCP endpoints:

Server	URL	Purpose
`CarbonArcMCP`	`https://mcp.carbonarc.ai`	Core tools — discovery and natural-language insight queries
`CarbonArcResearchMCP`	`https://mcp.carbonarc.ai/research`	Research tools — Entity Research, Forecast, Acquire, Retain, Target, Upsell

Setup Instructions

Step 1: Create the API Integration

The API integration stores the connection and OAuth configuration Snowflake uses to reach the Carbon Arc MCP server. Carbon Arc supports OAuth with Dynamic Client Registration (DCR), so no client ID or secret needs to be provisioned in advance. Run the following as an account admin:

CREATE API INTEGRATION carbonarc_mcp_api_integration
  API_PROVIDER = external_mcp
  API_ALLOWED_PREFIXES = ('https://mcp.carbonarc.ai')
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH_DYNAMIC_CLIENT
    OAUTH_RESOURCE_URL = 'https://mcp.carbonarc.ai'
    OAUTH_ALLOWED_SCOPES = ('openid', 'profile', 'email', 'offline_access')
  )
  ENABLED = TRUE;

Set scopes at CREATE time

OAUTH_ALLOWED_SCOPES must be set when the API integration is created — it cannot be added later via ALTER (Snowflake only allows altering scopes on TYPE = OAUTH2 integrations, not OAUTH_DYNAMIC_CLIENT). Omitting it causes Snowflake to send an empty scope, and sign-in fails with scope must be provided.

If your organization requires a standard OAuth client (client ID and secret) instead of DCR, contact support@carbonarc.co.

Step 2: Create the External MCP Server

Create an external MCP server object that references the API integration. This object is schema-level, so set your session context first, or fully qualify the name (e.g. <your_db>.<your_schema>.carbonarc_mcp_server) — an unqualified CREATE in a fresh session with no current database fails with This session does not have a current database.

USE DATABASE <your_db>;
USE SCHEMA <your_schema>;

CREATE EXTERNAL MCP SERVER carbonarc_mcp_server
  WITH DISPLAY_NAME = 'Carbon Arc'
  URL = 'https://mcp.carbonarc.ai'
  API_INTEGRATION = carbonarc_mcp_api_integration;

Optionally, add the Research tools as a second server (it can reuse the same API integration since the URL shares the allowed prefix):

CREATE EXTERNAL MCP SERVER carbonarc_research_mcp_server
  WITH DISPLAY_NAME = 'Carbon Arc Research'
  URL = 'https://mcp.carbonarc.ai/research'
  API_INTEGRATION = carbonarc_mcp_api_integration;

Step 3: Add the Connector to Your Cortex Agent

Reference the MCP server in your agent's specification, either via the Snowsight Agent Admin UI or SQL:

Option A — Snowsight UI

Select your agent → MCP Connectors → Add to agent.

Option B — SQL

ALTER AGENT my_insights_agent MODIFY LIVE VERSION SET SPECIFICATION = $$
    <previous_spec>
    mcp_servers:
      - server_spec:
         name: "<your_db>.<your_schema>.carbonarc_mcp_server"
      # Optional: include only if you created the Research server in Step 2
      - server_spec:
         name: "<your_db>.<your_schema>.carbonarc_research_mcp_server"
$$;

SET SPECIFICATION replaces the agent's entire specification, so run DESCRIBE AGENT my_insights_agent first and paste the full existing spec in place of <previous_spec> — otherwise the agent's current models, instructions, and tools are overwritten.

Note the SET SPECIFICATION = $$…$$ syntax — SET SPECIFICATION $$…$$ (without =) will fail.

Option C — Agent Object REST API

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}

{
  "comment": "Agent with Carbon Arc alternative data",
  "profile": { "display_name": "Insights Agent" },
  "models": { "orchestration": "auto" },
  "mcp_servers": [
    { "server_spec": { "name": "<your_db>.<your_schema>.carbonarc_mcp_server" } },
    { "server_spec": { "name": "<your_db>.<your_schema>.carbonarc_research_mcp_server" } }
  ]
}

server_spec must be an object with a name field, not a bare string. The second mcp_servers entry (carbonarc_research_mcp_server) is optional — remove it if you didn't create the Research server in Step 2.

PUT doesn't replace the whole agent: fields you leave out are kept, but each field you send replaces its current value. Sending mcp_servers removes any server not in the list, so include every server the agent should keep. The comment, profile, and models values above are only examples.

Grant access deliberately

Access to an MCP server does not automatically grant access to its tools — grant USAGE on the MCP server and its API integration only to the roles that need Carbon Arc data, following least-privilege practice:

GRANT USAGE ON EXTERNAL MCP SERVER <your_db>.<your_schema>.carbonarc_mcp_server TO ROLE <role>;
GRANT USAGE ON EXTERNAL MCP SERVER <your_db>.<your_schema>.carbonarc_research_mcp_server TO ROLE <role>;  -- Optional: if you created the Research server
GRANT USAGE ON INTEGRATION carbonarc_mcp_api_integration TO ROLE <role>;

Roles that need to alter or describe the MCP server also need the MODIFY privilege on it; dropping it requires OWNERSHIP.

Step 4: Connect and Authenticate as a User

In Snowflake CoWork:

Open CoWork and navigate to your agent.
Open the sources panel and select Connectors.
Select Connect next to Carbon Arc (or use Manage Connections → Connect).
A browser window opens — sign in with your Carbon Arc platform credentials.
Once the connector shows Connected, start asking questions. Connectors that aren't Connected are excluded from the agent's orchestration.

Via the Agent:run API, complete the OAuth flow in-session:

-- Returns the authorization URL; open it in a browser and sign in to Carbon Arc
SELECT SYSTEM$START_USER_OAUTH_FLOW('CARBONARC_MCP_API_INTEGRATION');

-- Then finish the flow in the same session with the redirect query string
SELECT SYSTEM$FINISH_OAUTH_FLOW('<query_string>');

When a token expires, CoWork prompts the user to re-authenticate.

Try It Out

Once connected, ask your agent questions like:

"What was Walmart's card spend in Q1 2024?"

"Compare website traffic for Nike and Adidas over the last 12 months."

"Which entities and insights are available for the airline industry?"

The Carbon Arc MCP translates each question into a structured analytical framework and returns formatted results with metadata and follow-up options. Discovery tools (entity and insight search) are free; query-execution tools incur consumption-based billing — see MCP Pricing.

Managing the Connector

-- List Carbon Arc MCP servers
SHOW EXTERNAL MCP SERVERS IN ACCOUNT;

-- Inspect configuration
DESCRIBE EXTERNAL MCP SERVER <your_db>.<your_schema>.carbonarc_mcp_server;
DESCRIBE EXTERNAL MCP SERVER <your_db>.<your_schema>.carbonarc_research_mcp_server;  -- Optional: if you created the Research server

-- Temporarily disable (invalidates all user tokens immediately)
ALTER API INTEGRATION carbonarc_mcp_api_integration SET ENABLED = FALSE;

-- Re-enable (users must re-authenticate)
ALTER API INTEGRATION carbonarc_mcp_api_integration SET ENABLED = TRUE;

-- Decommission: drop the server(s) first, then the integration.
-- Snowflake doesn't enforce this order; dropping the integration first succeeds
-- but leaves the servers pointing at nothing.
DROP EXTERNAL MCP SERVER <your_db>.<your_schema>.carbonarc_mcp_server;
DROP EXTERNAL MCP SERVER <your_db>.<your_schema>.carbonarc_research_mcp_server;  -- Optional: if you created the Research server
DROP API INTEGRATION carbonarc_mcp_api_integration;

caution

Disabling an API integration immediately blocks tool calls for every agent using it and invalidates user tokens; CoWork alerts users when a connector is disabled. Dropping an API integration permanently deletes its OAuth configuration and stored secrets — disable for maintenance, and only drop when decommissioning.

Tips for Snowflake

If sign-in fails with scope must be provided, confirm OAUTH_ALLOWED_SCOPES was set on the API integration at create time — it cannot be added later via ALTER
Snowflake supports OAuth only for MCP connections — each user signs in with their own Carbon Arc credentials, so entitlements stay intact
Use hyphens, never underscores, in any hostname you configure — underscores cause connection failures
MCP tool calls are recorded in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS as part of the agent trace (tool names, latency, and token usage); use Carbon Arc's usage reporting in the User Portal to track Carbon Arc consumption
Snowflake external MCP servers support tools only — MCP resources, prompts, notifications, and sampling are not supported
Until a user signs in, the agent answers without Carbon Arc tools, and agent:run returns warning 003001 ("User authentication required for MCP server") — complete Step 4 for that user
If the agent skips Carbon Arc tools, try adding "use MCP tools" to your prompt, and include a specific metric (card spend, web traffic, box office revenue) in data questions for best results
If you hit unexpected errors, double-check syntax against the latest Snowflake MCP Connectors documentation

Next Steps

Learn about MCP Best Practices
Explore the MCP Tools available
Review MCP Pricing