CREATE MCP SERVER¶

Creates a new MCP (Model Context Protocol) server or replaces an existing MCP server.

See also:: DESCRIBE MCP SERVER, DROP MCP SERVER, SHOW MCP SERVERS

Syntax¶

CREATE [ OR REPLACE ] MCP SERVER [ IF NOT EXISTS ] <name>
  FROM SPECIFICATION $$<specification_yaml>$$

Parameters¶

name

String that specifies the identifier for the MCP server; must be unique for the schema in which the MCP server is created.

In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (for example, "My object"). Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

FROM SPECIFICATION $$specification_yaml$$

Specifies the YAML specification defining the tools and configuration for the MCP server.

The specification must include a tools array with one or more tool definitions. Each tool must specify:

name: Unique identifier for the tool
type: Tool type (see supported tool types)
title: Human-readable title for the tool
description: Description of what the tool does

For GENERIC and CORTEX_AGENT_RUN tools, you can also specify an optional annotations object with MCP tool behavior hints:

readOnlyHint: If true, the tool doesn’t modify its environment.
destructiveHint: If true, the tool might perform destructive updates. This hint is meaningful only when readOnlyHint is false.
idempotentHint: If true, repeated calls with the same arguments have the same effect as one call.
openWorldHint: If true, the tool might interact with external entities.

Each annotation is optional. For omitted annotations, Snowflake uses the default for the tool type. The defaults for GENERIC and CORTEX_AGENT_RUN are readOnlyHint: false, destructiveHint: true, idempotentHint: false, and openWorldHint: true.

Tool annotations are hints for MCP clients. They don’t enforce tool behavior or replace access control. Configure privileges for the underlying object according to the actual operations that the tool can perform.

Supported tool types:

CORTEX_SEARCH_SERVICE_QUERY: Cortex Search Service tool
CORTEX_ANALYST_MESSAGE: Cortex Analyst tool
SYSTEM_EXECUTE_SQL: SQL execution tool
CORTEX_AGENT_RUN: Cortex Agent tool
CODING_AGENT: Coding Agent tool, with no stored agent object. Snowflake adds the code_toolset_all tool on every run
GENERIC: Custom tool for UDFs and stored procedures

Tool-specific requirements:

For CORTEX_SEARCH_SERVICE_QUERY, CORTEX_ANALYST_MESSAGE, and CORTEX_AGENT_RUN tools:

identifier: Fully qualified name of the underlying object (for example, database.schema.object_name)

For GENERIC tools:

identifier: Fully qualified name of the UDF or stored procedure
config: Configuration object specifying:
- type: Either function (for UDF) or procedure (for stored procedure)
- warehouse: Warehouse to use for execution
- input_schema: JSON schema defining the function/procedure parameters

For CODING_AGENT tools:

Add the tool to the server specification. Omit identifier. This tool does not reference a stored agent object.
config: Optional agent configuration, such as model, instructions, tools, tool_resources, and skills. Leave messages, thread_id, parent_message_id, stream, background, and origin_application out of config. See Coding Agent.
Snowflake appends code_toolset_all after any tools in config. A run can include code_toolset_all or code_execution, but not both.

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:

Privilege	Object
CREATE MCP SERVER	Schema
USAGE	Schema

For tools that reference other objects, additional privileges are required:

Privilege	Object
USAGE	Cortex Search Service (for CORTEX_SEARCH_SERVICE_QUERY tools)
SELECT	Semantic View (for CORTEX_ANALYST_MESSAGE tools)
USAGE	Cortex Agent (for CORTEX_AGENT_RUN tools)
USAGE	User-defined function or stored procedure (for GENERIC tools)
USAGE	Warehouse (for GENERIC tools)

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Usage notes¶

The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can’t both be used in the same statement.
CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.
When configuring hostnames for MCP server connections, use hyphens (-) instead of underscores (_). MCP servers have connection issues with hostnames containing underscores.
External OAuth authorization-server binding and advertised scopes aren’t set in the MCP server specification. Configure them with the OAUTH_AUTHORIZATION_SERVER and OAUTH_SCOPES_SUPPORTED parameters on the enclosing account, database, or schema. For details, see Configure External OAuth authentication for MCP servers.
The MCP server specification is stored as metadata and can be viewed using DESCRIBE MCP SERVER.
Multiple tools can be defined in a single MCP server specification.
Tool names must be unique within a single MCP server.
Regarding metadata:

Attention

Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

Examples¶

Example 1: Create MCP server with Cortex Search and Analyst tools

CREATE MCP SERVER my_mcp_server
  FROM SPECIFICATION $$
    tools:
      - name: "product-search"
        type: "CORTEX_SEARCH_SERVICE_QUERY"
        identifier: "database1.schema1.cortex_search_service1"
        description: "Cortex search service for all products"
        title: "Product Search"

      - name: "revenue-semantic-view"
        type: "CORTEX_ANALYST_MESSAGE"
        identifier: "database1.schema1.semantic_view_1"
        description: "Semantic view for all revenue tables"
        title: "Semantic view for revenue"
  $$;

Example 2: Create MCP server with SQL execution tool

CREATE MCP SERVER sql_exec_server
  FROM SPECIFICATION $$
    tools:
      - title: "SQL Execution Tool"
        name: "sql_exec_tool"
        type: "SYSTEM_EXECUTE_SQL"
        description: "A tool to execute SQL queries against the connected Snowflake database."
  $$;

Example 3: Create MCP server with custom UDF tool

CREATE MCP SERVER custom_tools_server
  FROM SPECIFICATION $$
    tools:
      - title: "Multiply by Ten"
        identifier: "example_database.agents.multiply_by_ten"
        name: "multiply_by_ten"
        type: "GENERIC"
        description: "Multiplies input value by ten and returns the result."
        config:
          type: "function"
          warehouse: "compute_service_warehouse"
          input_schema:
            type: "object"
            properties:
              x:
                description: "A number to be multiplied by ten"
                type: "number"
  $$;

Example 4: Create MCP server with custom stored procedure tool

CREATE MCP SERVER procedure_tools_server
  FROM SPECIFICATION $$
    tools:
      - title: "Calculate Values"
        identifier: "example_database.agents.calculate_values_sp"
        name: "calculate_values_sp"
        type: "GENERIC"
        description: "Calculates the product and sum of two numbers and returns them in a JSON object."
        annotations:
          readOnlyHint: true
          destructiveHint: false
          idempotentHint: true
          openWorldHint: false
        config:
          type: "procedure"
          warehouse: "compute_service_warehouse"
          input_schema:
            type: "object"
            properties:
              x:
                description: "First number"
                type: "number"
              y:
                description: "Second number"
                type: "number"
  $$;

Example 5: Create MCP server with Agent tool

CREATE MCP SERVER agent_server
  FROM SPECIFICATION $$
    tools:
      - title: "Customer Service Agent"
        name: "customer_agent"
        type: "CORTEX_AGENT_RUN"
        identifier: "support_db.agents_schema.customer_service_agent"
        description: "Agent that handles customer service inquiries"
        annotations:
          openWorldHint: false
  $$;

Example 6: Create MCP server with a coding agent tool

Add a CODING_AGENT tool to the server specification. Clients call the tool with a text argument and can pass thread_id to continue the conversation.

CREATE MCP SERVER coding_agent_server
  FROM SPECIFICATION $$
    tools:
      - title: "Coding agent"
        name: "ask_coding_agent"
        type: "CODING_AGENT"
        description: "Ask the coding agent. code_toolset_all gives the agent a managed sandbox where it can write and run code. That sandbox stays attached to the conversation thread."
        config:
          model: "claude-sonnet-4-6"
          instructions:
            response: "Write and run code when that answers the question."
  $$;