Snowflake Integration

Connect your Snowflake data warehouse to Phoenix so your AI agents can query your first-party customer data alongside HG Insights enrichment.

Prerequisites

Before you begin, ensure you have:

• A Snowflake account (trial or enterprise)
• A database containing first-party customer or account data
• A dedicated read-only service user (recommended for production use)

Create a Read-Only Service User

We recommend creating a dedicated Snowflake user for Phoenix with minimal privileges:

-- Create a role with read-only access
CREATE ROLE phoenix_role;
GRANT USAGE ON DATABASE your_database TO ROLE phoenix_role;
GRANT USAGE ON SCHEMA your_database.your_schema TO ROLE phoenix_role;
GRANT SELECT ON ALL TABLES IN SCHEMA your_database.your_schema TO ROLE phoenix_role;
GRANT SELECT ON FUTURE TABLES IN SCHEMA your_database.your_schema TO ROLE phoenix_role;

-- Create a service user
CREATE USER phoenix_user
  DEFAULT_ROLE = phoenix_role
  DEFAULT_WAREHOUSE = your_warehouse;

GRANT ROLE phoenix_role TO USER phoenix_user;

Authentication

Phoenix supports two authentication methods for Snowflake.

Password Authentication

The simplest option. Set a password on your service user:

ALTER USER phoenix_user SET PASSWORD = 'your-secure-password';

Key-Pair Authentication (Recommended)

Key-pair authentication is more secure and recommended for enterprise deployments. It uses an RSA key pair instead of a password.

1. Generate an encrypted private key:

openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes-256-cbc -inform PEM -out rsa_key.p8

You will be prompted to set an encryption passphrase. Remember it — you will enter it in Phoenix.

2. Extract the public key:

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

3. Assign the public key to your Snowflake user:

ALTER USER phoenix_user SET RSA_PUBLIC_KEY='MIIBIjANBgkqhk...';

Copy only the key body from rsa_key.pub (without the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines).

4. Verify the key fingerprint (optional):

DESC USER phoenix_user;
-- Check RSA_PUBLIC_KEY_FP matches your key

note

Phoenix decrypts the private key server-side. Paste the full encrypted PEM (including the -----BEGIN ENCRYPTED PRIVATE KEY----- and -----END ENCRYPTED PRIVATE KEY----- lines) along with your passphrase in the configuration UI.

Configure in Phoenix

1. Navigate to Marketplace in the sidebar
2. Find Snowflake and click Configure
3. Fill in the connection details:

Field	Required	Description	Example
Account	Yes	Your Snowflake account identifier	ORGID-ACCTID
Username	Yes	Service user name	PHOENIX_USER
Database	Yes	Database to connect to	ACME_DB
Schema	Yes	Default schema	PUBLIC
Warehouse	No	Compute warehouse (uses user default if omitted)	COMPUTE_WH
Role	No	Access role (uses user default if omitted)	PHOENIX_ROLE

4. Choose your authentication method:

   • Password — enter the user's password
   • Key Pair (recommended) — paste the full private key PEM and enter the passphrase

5. Click Test Connection to verify your credentials

6. Click Save once the connection test passes

Finding Your Account Identifier

Your Snowflake account identifier uses the ORG-ACCOUNT format. To find it:

1. Log in to Snowflake
2. Go to Admin > Accounts
3. Click the account link or the config file icon
4. Copy the ORG-ACCOUNT identifier (e.g., MYORG-MYACCOUNT)

warning

Do not use the legacy xy12345.us-east-1 format. Phoenix requires the ORG-ACCOUNT format.

Network Configuration

If your Snowflake account uses network policies, you must allow Phoenix's static egress IP addresses.

Phoenix IP addresses:

Region	IP Addresses
Portland, USA (us-west-2)	52.24.226.242, 52.88.137.242
San Francisco, USA (us-west-1)	52.52.35.205, 13.57.62.0
Washington, D.C., USA (us-east-1)	13.216.33.94, 54.86.150.171

Sample Snowflake SQL:

CREATE NETWORK POLICY phoenix_access
  ALLOWED_IP_LIST = (
    '52.24.226.242',
    '52.88.137.242',
    '52.52.35.205',
    '13.57.62.0',
    '13.216.33.94',
    '54.86.150.171'
  );

ALTER ACCOUNT SET NETWORK_POLICY = phoenix_access;

warning

If you already have a network policy, add these IPs to your existing policy rather than creating a new one. Snowflake only allows one active account-level network policy.

What You Get

Once configured, Phoenix makes two MCP tools available to your AI agents:

customer_data_explore

Discover the structure of your Snowflake data — schemas, tables, columns, and sample rows.

Available actions:

Action	Description	Required Parameters
list_schemas	List all schemas in the database	None
list_tables	List tables in a schema	schema
describe_table	Show column names, types, and nullability	schema, table
sample_data	Return sample rows from a table	schema, table

Example conversation:

You: What tables do I have in my Snowflake?

Agent uses customer_data_explore with action: list_schemas, then list_tables to discover your data.

customer_data_query

Run read-only SQL SELECT queries against your Snowflake data.

Parameters:

Parameter	Required	Description
query	Yes	A SQL SELECT or WITH statement
limit	No	Max rows to return (1-10,000; default: 100)

Security constraints:

• Only SELECT and WITH statements are allowed
• DDL and DML statements (INSERT, UPDATE, DELETE, DROP, etc.) are rejected
• Query timeout: 30 seconds
• Maximum rows per query: 10,000

Example conversation:

You: How many customers do we have by region?

Agent uses customer_data_query to run:

SELECT region, COUNT(*) as customer_count
FROM customers
GROUP BY region
ORDER BY customer_count DESC

Data Enrichment

When Snowflake is connected, your agents can combine your first-party data with HG Insights enrichment in a single conversation:

You: Which of our enterprise customers use Salesforce and have high IT spend?

The agent queries your customer table via customer_data_query, then enriches results with company_technographic and company_spend from HG Insights.

Troubleshooting

Private Key Errors

Error Message	Cause	Solution
"The private key is encrypted but no passphrase was provided"	You pasted an encrypted PEM without entering the passphrase	Enter the passphrase you set when generating the key
"Failed to decrypt private key — the passphrase is incorrect"	Wrong passphrase	Double-check the passphrase; regenerate the key pair if lost
"Invalid private key format"	PEM is incomplete or malformed	Paste the full PEM including the -----BEGIN ENCRYPTED PRIVATE KEY----- and -----END ENCRYPTED PRIVATE KEY----- lines
"Failed to read the private key"	PEM has encoding issues (e.g., extra whitespace or missing newlines)	Re-copy the PEM from the original file; ensure no trailing whitespace

Connection Errors

Symptom	Likely Cause	Solution
Connection timeout	Network policy blocking Phoenix	Add Phoenix IPs to your Snowflake network policy (see Network Configuration)
"Incorrect username or password"	Wrong credentials	Verify the username and password in Snowflake
"The requested database does not exist"	Wrong database name	Check the database name — Snowflake identifiers are case-sensitive if quoted
"The requested warehouse does not exist"	Wrong warehouse name, or user lacks access	Verify the warehouse name and grants

Account Identifier Issues

If you see authentication errors despite correct credentials, verify your account identifier format:

• Correct: MYORG-MYACCOUNT (from Admin > Accounts)
• Incorrect: xy12345.us-east-1 (legacy format)
• Incorrect: myorg-myaccount.snowflakecomputing.com (full URL)

Next Steps

• Best Practices for using Phoenix MCP tools effectively
• Supported MCP Clients to connect Phoenix to your AI tools
• MCP Tool Documentation for the full tool catalog