Use Cortex Agents and MCP servers in an app¶

Security model¶

Cortex Agents created by an app run under restricted caller’s rights (RCR). RCR enforces that an app’s agent can’t access consumer data without an explicit grant from the consumer.

Every tool invocation from an app-created agent requires both of the following:

• Consumer privilege: a user in the consumer account has the privilege needed on the target object. This is the same caller’s-rights model used by standalone agents.

• App caller grant: the consumer admin has performed a caller grant to the app for the object. For more information, see GRANT CALLER.

Key points:

• The app gets implicit caller grants on objects that it owns. The provider doesn’t need to request explicit caller grants for in-app objects.

• Consumer-owned objects require explicit GRANT CALLER ... TO APPLICATION from the consumer admin.

• When a tool runs in owner’s rights (for example, a procedure created with EXECUTE AS OWNER), execution switches to the owner’s identity. RCR restrictions don’t apply within that tool’s scope.

• When a tool runs in restricted caller’s rights, for example a procedure created with EXECUTE AS RESTRICTED CALLER and owned by a role other than the app, RCR restrictions compose by intersection. Each link in a chain makes the effective access stricter, never looser.

• Owner’s rights agents aren’t supported. A provider can still surface an agent through an owner’s-rights code entity (for example, a Streamlit app or an Snowpark Container Services service) that calls the agent using the app’s identity.

Snowflake-managed MCP servers created by an app are restricted to app-owned tools. They can’t expose tools that aren’t owned by the app, and they can’t include the SYSTEM_EXECUTE_SQL tool. This restriction prevents an installed app’s MCP server from being used as a way to access consumer data or run arbitrary SQL in the consumer’s account.

Before you begin¶

To use Cortex Agents in a Snowflake Native App, the consumer account must have both Cortex Agents and Snowflake Intelligence enabled. For more information, see Cortex Agents.

Provider: Create the agent¶

A provider creates an agent in the app’s setup script, or at runtime in a code entity. The following example creates an agent that includes a Cortex Analyst tool backed by an app-owned semantic view, a second Cortex Analyst tool backed by a consumer-owned semantic view, and a custom procedure tool that calls an app-owned procedure:

CREATE OR REPLACE AGENT core.my_agent
  FROM SPECIFICATION $$
models:
  orchestration: auto
instructions:
  system: "You are a helpful assistant for financial analysis."
tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "Analyst1"
      description: "Answers questions about the app's financial data"
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "Analyst2"
      description: "Answers questions about the consumer's portfolio data"
  - tool_spec:
      type: generic
      name: Procedure1
      description: "Return current app metadata about the specified category"
      input_schema:
        type: object
        properties:
          category:
            type: string
            description: "Category of metadata to return"
        required: ["category"]
tool_resources:
  Analyst1:
    semantic_view: "core.my_semantic_view"
    execution_environment:
      type: warehouse
      warehouse: "MY_APP_WH"
  Analyst2:
    semantic_view: "consumer_db.public.consumer_semantic_view"
    execution_environment:
      type: warehouse
      warehouse: "MY_APP_WH"
  Procedure1:
    identifier: core.get_app_metadata
    type: procedure
    execution_environment:
      type: warehouse
      warehouse: "MY_APP_WH"
$$;

Notes:

• Partially qualified identifiers (such as core.my_semantic_view) are resolved relative to the agent’s database and schema. This is the recommended pattern inside a Snowflake Native App, because the app database name is only known at install time.

• Tool identifiers aren’t resolved when the agent is created. A provider can declare tools before the underlying objects are created or before the app has access to them.

• We recommend using orchestration: auto instead of a specific model name. A specific model might not be available in the consumer’s region.

For information about Cortex Agent SQL commands, see Cortex Agent commands.

Provider: Create the tools and grant access¶

The application also creates the tools that the agent uses and grants access to them through application roles:

CREATE SEMANTIC VIEW core.my_semantic_view ...;
CREATE PROCEDURE core.get_app_metadata(category STRING) RETURNS STRING ...;

GRANT USAGE ON AGENT core.my_agent TO APPLICATION ROLE my_app_role;

GRANT SELECT ON SEMANTIC VIEW core.my_semantic_view
  TO APPLICATION ROLE my_app_role;
GRANT USAGE ON PROCEDURE core.get_app_metadata(STRING)
  TO APPLICATION ROLE my_app_role;

Consumer admin: Audit the agent before granting access¶

Before granting users access to an app-created agent, the consumer admin should review the agent’s full specification (model, tools, system prompt, and referenced objects) by using DESCRIBE AGENT or through the agent UI:

DESC AGENT my_app.core.my_agent;

Consumer admin: Grant caller access on consumer objects¶

Without caller grants, the agent can’t use consumer objects, even if the consumer user has privileges on them. The following example grants the app the caller privileges that the agent needs:

GRANT CALLER USAGE ON WAREHOUSE my_app_wh TO APPLICATION my_app;

GRANT CALLER USAGE ON DATABASE my_db TO APPLICATION my_app;
GRANT CALLER USAGE ON SCHEMA my_db.my_schema TO APPLICATION my_app;

GRANT INHERITED CALLER SELECT ON ALL SEMANTIC VIEWS IN SCHEMA my_db.my_schema
  TO APPLICATION my_app;
GRANT INHERITED CALLER SELECT ON ALL TABLES IN SCHEMA my_db.my_schema
  TO APPLICATION my_app;

Alternatively, grant access to individual objects:

GRANT CALLER SELECT ON SEMANTIC VIEW my_db.my_schema.consumer_semantic_view
  TO APPLICATION my_app;
GRANT CALLER SELECT ON TABLE my_db.my_schema.my_sv_underlying_table
  TO APPLICATION my_app;

For more information about caller grants, see GRANT CALLER.

Consumer admin: Delegate to user roles¶

After granting caller access to the app, delegate access to the underlying objects and the application role to the user roles that should be allowed to use the agent:

GRANT USAGE ON DATABASE my_db TO ROLE analyst_role;
GRANT USAGE ON SCHEMA my_db.my_schema TO ROLE analyst_role;
GRANT SELECT ON SEMANTIC VIEW my_db.my_schema.my_sv TO ROLE analyst_role;
GRANT SELECT ON TABLE my_db.my_schema.my_sv_underlying_table
  TO ROLE analyst_role;

GRANT APPLICATION ROLE my_app.app_public TO ROLE analyst_role;

Use the agent¶

After the consumer admin grants the application role to a user role, the agent is available in all the same places as a standalone agent. For example:

• Snowflake Intelligence. The agent appears automatically.

• The Cortex Agents REST API. Send a request to POST /api/v2/databases/{app}/schemas/{schema}/agents/{name}:run. For more information, see Cortex Agents REST API.

• SQL. Call DATA_AGENT_RUN (SNOWFLAKE.CORTEX).

SPCS-hosted MCP servers¶

An SPCS-hosted MCP server is a metadata object that links an SPCS service endpoint to the MCP client infrastructure used by Cortex Agents and Snowflake Intelligence. It doesn’t deploy a service. It registers an existing SPCS endpoint as MCP-discoverable. For information about how to deploy SPCS services in a Snowflake Native App, see Tutorial 2: Create an app with containers.

"""Example MCP echo server -- Streamable HTTP transport on port 8080."""

import os
import threading
from http.server import HTTPServer, BaseHTTPRequestHandler

from mcp.server.fastmcp import FastMCP

os.environ.setdefault("FASTMCP_PORT", "8080")
os.environ.setdefault("FASTMCP_HOST", "0.0.0.0")

mcp = FastMCP("echo-server", host="0.0.0.0", port=8080)

@mcp.tool()
def echo(message: str) -> str:
    """Echo back the provided message."""
    return f"Echo: {message}"

@mcp.tool()
def reverse(text: str) -> str:
    """Reverse the provided text string."""
    return text[::-1]

class HealthHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/health":
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(b'{"status":"ok"}')
        else:
            self.send_response(404)
            self.end_headers()

    def log_message(self, format, *args):
        pass

def start_health_server():
    server = HTTPServer(("0.0.0.0", 8081), HealthHandler)
    server.serve_forever()

if __name__ == "__main__":
    health_thread = threading.Thread(target=start_health_server, daemon=True)
    health_thread.start()
    mcp.run(transport="streamable-http")

CREATE SERVICE IF NOT EXISTS services.my_service
  IN COMPUTE POOL my_app_pool
  FROM SPECIFICATION '
spec:
  containers:
    - name: server
      image: /MY_APP_PKG/IMG/REPO/my-server:latest
      readinessProbe:
        port: 8081
        path: /health
  endpoints:
    - name: mcp_endpoint
      port: 8080
      public: true
';

GRANT SERVICE ROLE services.my_service!ALL_ENDPOINTS
  TO APPLICATION ROLE my_app_role;

CREATE CUSTOM MCP SERVER IF NOT EXISTS services.my_mcp_server
  SERVICE = services.my_service
  ENDPOINT = mcp_endpoint
  PATH = '/mcp';

GRANT USAGE ON CUSTOM MCP SERVER services.my_mcp_server
  TO APPLICATION ROLE my_app_role;

SHOW CUSTOM MCP SERVERS IN APPLICATION my_app;

-- Display the URL of the SPCS-hosted MCP server.
DESC CUSTOM MCP SERVER my_app.services.my_mcp_server;

mcp_servers:
  - server_spec:
      name: "MY_APP.SERVICES.MY_MCP_SERVER"

Snowflake-managed MCP servers¶

A Snowflake-managed MCP server (created with CREATE MCP SERVER) wraps Snowflake-native objects as MCP tools. For general information about Snowflake-managed MCP servers, see Snowflake-managed MCP server.

CREATE MCP SERVER core.my_mcp
  FROM SPECIFICATION $$
tools:
  - name: "product-search"
    type: "CORTEX_SEARCH_SERVICE_QUERY"
    identifier: "core.my_search_service"
    description: "Cortex Search service for all products"
    title: "Product Search"
  - name: "revenue-semantic-view"
    type: "CORTEX_ANALYST_MESSAGE"
    identifier: "core.my_semantic_view"
    description: "Semantic view for all revenue tables"
    title: "Semantic view for revenue"
$$;

GRANT USAGE ON MCP SERVER core.my_mcp TO APPLICATION ROLE app_public;

https://<account>/api/v2/databases/{app}/schemas/{schema}/mcp-servers/{name}