Title: Snowflake-managed MCP server | Snowflake Documentation
URL Source: https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp
Published Time: Sat, 04 Jul 2026 02:39:16 GMT
Markdown Content:
Overview¶
Note
Snowflake supports Model Context Protocol revision 2025-11-25.
Model Context Protocol (MCP) is an open-source standard that lets AI agents securely interact with business applications and external data systems, such as databases and content repositories. MCP lets enterprise businesses reduce integration challenges and quickly deliver outcomes from models. Since its launch, MCP has become foundational for agentic applications, providing a consistent and secure mechanism for invoking tools and retrieving data.
The Snowflake-managed MCP server lets AI agents securely retrieve data from Snowflake accounts without needing to deploy separate infrastructure. You can configure the MCP server to serve Cortex Analyst, Cortex Search, and Cortex Agents as tools, along with custom tools and SQL executions on the standards-based interface. MCP clients discover and invoke these tools, and retrieve data required for the application. With managed MCP servers on Snowflake, you can build scalable enterprise-grade applications while maintaining access and privacy controls. The MCP server on Snowflake provides:
- Standardized integration: Unified interface for tool discovery and invocation, in compliance with the rapidly evolving standards.
- Comprehensive authentication: Snowflake OAuth by default, with optional External OAuth so MCP clients can authenticate against your organization’s identity provider.
- Robust governance: role-based access control (RBAC) for the MCP server and tools to manage tool discovery and invocation.
For information about the MCP lifecycle, see Lifecycle. For an example of an MCP implementation, see the Getting Started with Managed Snowflake MCP Server Quickstart.
MCP server security recommendations¶
Important
When you configure hostnames for MCP server connections, use hyphens (-) instead of underscores (_). MCP servers have connection issues with hostnames containing underscores.
Using multiple MCP servers without verifying tools and descriptions could lead to vulnerabilities such as tool poisoning or tool shadowing. Snowflake recommends verifying third-party MCP servers before using them. This includes any MCP server from another Snowflake user or account. Verify all tools offered by third-party MCP servers.
We recommend using OAuth as the authentication method. Using hardcoded tokens can lead to token leakage.
When using a Programmatic Access Token (PAT), set it to use the least-privileged role allowed to work with MCP. This will help prevent leaking a secret with access to a highly-privileged role.
Configure proper permissions for the MCP server and tools following the least-privilege principle. Access to the MCP Server does not give access to the tools. Permission needs to be granted for each tool.
Avoid configurations that can create recursive loops. For example, an external client calling a Cortex Agent tool through MCP, which in turn invokes another MCP server that calls back into a Cortex Agent, can produce expensive, unbounded loops. Snowflake enforces a maximum recursion depth of 10 invocations. Ensure your agent and tool configurations don’t create circular invocation paths.
Create an MCP server object¶
Create an object, specifying the tools and other metadata. MCP clients that connect with the server, after requisite authentication, are able to discover and invoke these tools.
- Navigate to the database and schema where you want to create the MCP server.
- Create the MCP server by using the following syntax:CREATE [ OR REPLACE ] MCP SERVER [ IF NOT EXISTS ] <server_name>
FROM SPECIFICATION $$ <specification_yaml> $$;
For business data applications that require governed orchestration, Snowflake recommends exposing a Cortex Agent as the client-facing MCP tool. Configure the agent with the Cortex Analyst, Cortex Search, and custom tools that it needs, and then expose the agent through the MCP server. This configuration gives the external MCP client one governed interface and lets the agent select the appropriate resources for each request.
The following example exposes only a Cortex Agent:
CREATE OR REPLACE MCP SERVER <database_name>.<schema_name>.<server_name>
FROM SPECIFICATION $$
tools:
- title: "Governed business data agent"
name: "business_data_agent"
type: "CORTEX_AGENT_RUN"
identifier: "<database_name>.<schema_name>.<agent_name>"
description: "Use this agent for governed business data questions."
$$;
When an MCP client sends a question, the client selects the agent based on its name and description. The MCP server passes the question to the agent. The agent then selects and orchestrates its configured Cortex Analyst, Cortex Search, or custom tools and returns the response to the client.
Use precise, domain-specific names and descriptions when you expose multiple agents. This information helps the MCP client select the correct agent.
Expose Cortex Analyst or Cortex Search directly when you want the external MCP client to select those resources independently. A directly exposed Cortex Analyst tool generates SQL and returns the statement to the client. A SQL execution tool runs queries without Cortex Agent orchestration.
Configure tool types¶
Snowflake currently supports the following tool types:
- CORTEX_AGENT_RUN: Cortex Agent tool
- CORTEX_SEARCH_SERVICE_QUERY: Cortex Search Service tool
- CORTEX_ANALYST_MESSAGE: Cortex Analyst tool
- SYSTEM_EXECUTE_SQL: SQL execution
- GENERIC: tool for UDFs and stored procedures
The following examples show how to configure different tool types:
For the Agent tool, your client passes a message to the agent. The agent processes the request and returns a response. Use the following code to specify the tool configuration.
tools:
- title: "Governed business data agent"
name: "business_data_agent"
type: "CORTEX_AGENT_RUN"
identifier: "<database_name>.<schema_name>.<agent_name>"
description: "Answers governed business data questions by using configured Cortex Analyst and Cortex Search resources."
The agent tool response includes all intermediate steps by design: reasoning traces, tool calls, search results, and citations. This can result in large response payloads (200 KB or more). To reduce the payload size when the agent uses Cortex Search, configure max_results in the agent’s search tool resources to limit the number of search results returned per query.
Use the following examples to create and configure custom tools using UDFs and stored procedures:
The following examples demonstrate creating UDFs that can be used as custom tools:
-- create a simple udf
CREATE OR REPLACE FUNCTION MULTIPLY_BY_TEN(x FLOAT)
RETURNS FLOAT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.13'
HANDLER = 'multiply_by_ten'
AS
$$
def multiply_by_ten(x: float) -> float:
return x * 10
$$;
SHOW FUNCTIONS LIKE 'MULTIPLY_BY_TEN';
-- test return json/variant
CREATE OR REPLACE FUNCTION CALCULATE_PRODUCT_AND_SUM(x FLOAT, y FLOAT)
RETURNS VARIANT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.13'
HANDLER = 'calculate_values'
AS
$$
import json
def calculate_values(x: float, y: float) -> dict:
"""
Calculates the product and sum of two numbers and returns them in a dictionary.
The dictionary is converted to a VARIANT (JSON) in the SQL return.
"""
product = x * y
sum_val = x + y
return {
"product": product,
"sum": sum_val
}
$$;
-- test return list/array
CREATE OR REPLACE FUNCTION GET_NUMBERS_IN_RANGE(x FLOAT, y FLOAT)
RETURNS ARRAY -- Use ARRAY to explicitly state a list is being returned
LANGUAGE PYTHON
RUNTIME_VERSION = '3.13'
HANDLER = 'get_numbers'
AS
$$
def get_numbers(x: float, y: float) -> list:
"""
Returns a list of integers between x (exclusive) and y (inclusive).
Assumes x < y.
"""
Ensure x and y are treated as integers for range generation
start = int(x) + 1
end = int(y) + 1 # range() is exclusive on the stop value
Use a list comprehension to generate the numbers
The Python list will be converted to a Snowflake ARRAY.
return list(range(start, end))
$$;
Manage MCP server objects¶
After you create an MCP server, use the following commands to inspect or remove it:
- To show MCP servers, use the following commands:
SHOW MCP SERVERS IN DATABASE <database_name>;
SHOW MCP SERVERS IN SCHEMA <schema_name>;
SHOW MCP SERVERS IN ACCOUNT;
The following shows the output of the command:
| created_on | name | database_name | schema_name | owner | comment |
------------------------------------------+-------------------+---------------+-------------+--------------+------------------------------
| Fri, 23 Jun 1967 07:00:00.123000 +0000 | TEST_MCP_SERVER | TEST_DATABASE | TEST_SCHEMA | ACCOUNTADMIN | [NULL] |
| Fri, 23 Jun 1967 07:00:00.123000 +0000 | TEST_MCP_SERVER_2 | TEST_DATABASE | TEST_SCHEMA | ACCOUNTADMIN | Test MCP server with comment |
2. To describe an MCP server, use the following command:
DESCRIBE MCP SERVER <server_name>;
The following shows the output of the command:
| name | database_name | schema_name | owner | comment | server_spec | created_on |
------------------------------------------------------------------------------------------------------+-------------------------------------
| TEST_MCP_SERVER | TEST_DATABASE | TEST_SCHEMA | ACCOUNTADMIN | [NULL] | {"version":1,"tools":[{"name":"product-search","identifier":"db.schema.search_service","type":"CORTEX_SEARCH_SERVICE_QUERY"}]} | Fri, 23 Jun 1967 07:00:00.123000 +0000 |
3. To drop an MCP server, use the following command:
DROP MCP SERVER <server_name>;
MCP server URL¶
To connect to the MCP server, use the URL endpoint with the following format:
https://<account_url>/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}
For information about formatting your account URL, see Account identifiers.
Access control¶
Required privileges¶
You can use the following privileges to manage access to the MCP server and the underlying tools.
| Privilege | Object | Description |
|---|
| CREATE | MCP SERVER | Required to create the MCP server |
| OWNERSHIP | MCP SERVER | Required to update the object configuration |
| MODIFY | MCP SERVER | Provides update, drop, describe, show, and use (tools/list and tools/call) on the object configuration |
| USAGE | MCP SERVER | Required to connect with the MCP server and discover tools |
| USAGE | Cortex Search Service | Required to invoke the Cortex Search tool in the MCP server |
| SELECT | Semantic View | Required to invoke the Cortex Analyst tool in the MCP server |
| USAGE | Cortex Agent | Required to invoke the Cortex Agent as a tool in the MCP server |
| USAGE | User-defined function (UDF) or stored procedure | Required to invoke the UDF or stored procedure as a tool in the MCP server |
Grant access to a Cortex Agent-based MCP server¶
The following example creates a dedicated access role and grants it access to an MCP server that exposes a Cortex Agent:
CREATE ROLE <mcp_access_role>;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE <mcp_access_role>;
GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE <mcp_access_role>;
GRANT USAGE ON DATABASE <database_name> TO ROLE <mcp_access_role>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> TO ROLE <mcp_access_role>;
GRANT USAGE ON MCP SERVER <database_name>.<schema_name>.<server_name> TO ROLE <mcp_access_role>;
GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <mcp_access_role>;
GRANT ROLE <mcp_access_role> TO USER ;
The role also needs privileges on the resources configured for the agent. Grant only the privileges for the resources that the agent uses. For example:
GRANT USAGE ON CORTEX SEARCH SERVICE <database_name>.<schema_name>.<search_service_name>
TO ROLE <mcp_access_role>;
GRANT SELECT ON SEMANTIC VIEW <database_name>.<schema_name>.<semantic_view_name>
TO ROLE <mcp_access_role>;
GRANT SELECT ON TABLE <database_name>.<schema_name>.<table_name>
TO ROLE <mcp_access_role>;
GRANT USAGE ON FUNCTION <database_name>.<schema_name>.<function_name>(<argument_type>)
TO ROLE <mcp_access_role>;
GRANT USAGE ON PROCEDURE <database_name>.<schema_name>.<procedure_name>(<argument_type>)
TO ROLE <mcp_access_role>;
For more information about agent privileges and the privileges required by agent tools, see Access control and authentication.
Grant the MCP access role only to users who need it. Don’t grant the role to PUBLIC or grant broad access to all current and future tables solely to support an MCP client.
Connect from common MCP clients¶
Once you have created the MCP server and the OAuth security integration, you can connect from any MCP-compatible client by pointing it at your MCP server URL:
https://<account_url>/api/v2/databases//schemas//mcp-servers/
Important
You may need to use hyphens (-) instead of underscores (_) in your account URL with some clients.
The following examples show how to register the Snowflake-hosted MCP server in commonly used clients. Replace the URL with your own MCP server URL.
Claude (both claude.ai and Claude Desktop) supports Snowflake MCP servers in the Claude Directory or as a Custom Connector. Claude handles the OAuth flow against the security integration you created above. For Anthropic’s general guidance, see Get started with custom connectors using remote MCP.
- In Claude, open Settings → Connectors.
- Click Add custom connector or search for Snowflake in Browse connectors.
- Provide a Name (for example,
Snowflake) and the MCP Server URL:https://<account_url>/api/v2/databases//schemas//mcp-servers/
- Add the client ID and secret from the security integration you created.
- Click Add. Claude opens a browser window and prompts you to sign in to Snowflake and approve the OAuth consent screen.
- After approving, the Snowflake tools appear in the connector list and can be used in any Claude conversation.
Note
When configuring the OAuth security integration for Claude, set OAUTH_REDIRECT_URI to the redirect URI shown by Claude during connector setup (typically https://claude.ai/api/mcp/auth_callback for claude.ai and a localhost URI for Claude Desktop). Claude requests the session:role:all scope; the session still uses the user’s DEFAULT_ROLE.
Network policies for MCP clients¶
If your Snowflake account has network policies enabled, you must allow inbound connections from your MCP client’s outbound IP addresses. When a remote MCP client (such as Claude, ChatGPT, or Cursor) connects to your Snowflake-managed MCP server, the request originates from the client provider’s infrastructure, not from the end user’s browser. If those IP addresses are not permitted by your network policy, the connection will be blocked.
When a network policy blocks the token request, Snowflake can return error: invalid_client from the /oauth/token-request endpoint. That error is the same response clients see for incorrect credentials or an unsupported authentication method, so check your network policy if client credentials and authentication method look correct.
To allow an MCP client to reach your Snowflake account, create a network rule that includes the client provider’s outbound IP addresses, then add that rule to your account’s network policy:
CREATE NETWORK RULE mcp_client_ingress_rule
MODE = INGRESS
TYPE = IPV4
VALUE_LIST = ('<client_provider_ip_1>', '<client_provider_ip_2>', ...);
ALTER NETWORK POLICY <your_policy_name> ADD ALLOWED_NETWORK_RULE_LIST = ('mcp_client_ingress_rule');
Replace the IP addresses with the outbound IPs published by your MCP client provider. For example, Anthropic publishes the outbound IP addresses used by Claude at https://platform.claude.com/docs/en/api/ip-addresses.
Note
This applies to all MCP client providers, not just Claude. Check your provider’s documentation for their outbound IP addresses used for remote MCP connections.
For Snowflake OAuth client authentication at the token endpoint, see Configure Snowflake OAuth for custom clients.
Troubleshoot MCP client connections¶
If your MCP client can’t connect or a tool doesn’t behave as expected, use this table to identify the likely cause:
| Symptom | Likely cause | Recommended check |
|---|
| OAuth consent or connection fails | The redirect URI doesn’t match the client configuration | Set OAUTH_REDIRECT_URI to the exact callback URI shown by the MCP client. |
| Authentication succeeds, but the MCP server doesn’t connect | The MCP server URL is incomplete | Use the fully qualified database, schema, and MCP server path. |
| The client reports a hostname-related connection failure | The account hostname contains underscores | Replace underscores (_) with hyphens (-) in the account hostname. |
| The session fails to initialize | The user doesn’t have a default warehouse | Set DEFAULT_WAREHOUSE on the user and grant the default role USAGE on that warehouse. |
| The session uses the wrong data access role | The user’s default role isn’t the MCP access role | Set and verify the user’s DEFAULT_ROLE. |
| Tools aren’t visible | The default role doesn’t have access to the MCP server | Grant USAGE on the MCP server to the user’s default role. |
Interact with the MCP server using a custom MCP client¶
For information about building a custom MCP client, see Build an MCP client.
Note
The Snowflake MCP server currently only supports tool capabilities.
Discover and invoke tools¶
The MCP clients can discover and invoke tools with tools/list and tools/call requests.
To discover or invoke tools, issue a POST call as shown in the tools/list request:
As of August 20, 2026, the server returns tools/call responses as a Server-Sent Events (SSE) stream rather than a single JSON body. Your client must list both content types in the Accept header:
Accept: application/json, text/event-stream
The response examples in this section show the JSON payload that the server sends in each data: event. The stream closes with a data: [DONE] event. Clients that follow the MCP specification (2025-11-25) handle this automatically. For details, see MCP: Streaming responses for tool calls (August 2026).
For the Analyst tool, your client passes messages in the request. The SQL statement is listed in the output. You must pass the name of the tool that you’re invoking in the request in the name parameter.
POST /api/v2/databases//schemas//mcp-servers/
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "test-analyst",
"arguments": {
"message": "text"
}
}
}
The following example shows the response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "string"
}
]
}
}
For Search tool requests, your client can pass the query and the following optional arguments:
The search results and request ID are returned in the output. You must pass the name of the tool that you’re invoking in the request as the name parameter.
POST /api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "product-search",
"arguments": {
"query": "Hotels in NYC",
"columns": array of strings,
"limit": int
}
}
}
The following example shows the response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"results": {}
}
}
Limitations¶
Snowflake-managed MCP server does not support the following constructs in the MCP protocol: resources, prompts, roots, notifications, version negotiations, life cycle phases, and sampling.
Each MCP server supports a maximum of 50 tools. This limit includes all tool types: Cortex Search, Cortex Analyst, Cortex Agents, SQL execution, and custom (generic) tools. If you need more tools, create additional MCP servers. Higher tool counts can degrade tool-selection accuracy.
Tool responses are subject to size limits to prevent LLM context window saturation:
- Generic tools: Responses are truncated at 250 KB.
- SQL execution tool: Responses are truncated at 250 KB.
If a query result exceeds the size limit, the response is truncated. To work around this limit, use narrower queries that return fewer columns or rows.
By default, MCP OAuth sessions use the connecting user’s DEFAULT_ROLE as the primary role. You can advertise other primary-role scopes with OAUTH_SCOPES_SUPPORTED. Secondary roles are controlled by the OAuth security integration; the recommended MCP configuration leaves them disabled (OAUTH_USE_SECONDARY_ROLES = NONE). For details, see Role behavior in OAuth sessions.
MCP server objects aren’t replicated in failover groups. If you use replication, you must recreate MCP server objects on the secondary account. OAuth security integrations are replicated.