This guide walks through how to build your own Cortex Agents MCP Server.

The core functionalities include:

In this tutorial, we'll build a simple MCP Cortex Agents server and connect it to an MCP host (Claude for Desktop). We'll start with a basic setup, then progress to more complex use cases.

What we'll be building

Many LLMs don't natively orchestrate external "agent" workflows. With MCP, we can expose Cortex Agents capabilities as first-class tools in your chat client.

We'll build a server that exposes one tool:

Then we'll connect the server to an MCP host (Claude for Desktop):

Note: you can connect any MCP-compatible client, but this guide uses Claude for Desktop for simplicity. See the official MCP client SDK guide for building your own, or browse other clients.

Prerequisites

What You Will Learn

What You Will Build

An MCP Server for Cortex Agents.

First install the MCP CLI (uv) and bootstrap your project:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
# restart your terminal to pick up `uv`

Windows

irm https://astral.sh/uv/install.ps1 | iex
# restart your shell

Configure and create your Cortex Agents project:

# Clone the repo
git clone https://github.com/Snowflake-Labs/sfguide-mcp-cortex-agent.git
cd sfguide-mcp-cortex-agent

# Create and activate venv
uv venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\Activate.ps1 # Windows PowerShell

# Install MCP SDK and HTTP client
uv add "mcp[cli]" httpx

Set the keys and services needed to run Cortex Agents by creating a .env following the .env.template with:

Run:

uv run cortex_agents.py

Note: Leave this (the MCP server) running while you call it from the MCP client.

Install or update Claude for Desktop.

Open your config file:

macOS / Linux

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Add your Cortex Agents server:

{
  "mcpServers": {
    "cortex-agent": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/sfguide-mcp-cortex-agent",
        "run",
        "cortex_agents.py"
      ]
    }
  }
}

Note: You may need to replace "uv" with the full uv path. You can find the uv path by running which uv.

Launch the Claude for Desktop app.

Now our Cortex Agents MCP server is available for use by Claude. We can see it by clicking on the tools icon, and toggle it on and off.

mcp tool in claude

Then, run a query. If the query calls your MCP server, you will see the name of the tool used directly below your query in the Claude desktop app.

Because we're connected to Cortex Agents, we can ask questions about both unstructured data (via Cortex Search) and structured data via Cortex Analyst.

Unstructured data:

cortex agents mcp unstructured

Structured data:

cortex agents mcp unstructured

What's happening under the hood When you ask a question:

  1. The client sends your question to Claude
  2. Claude analyzes the available tools and decides which one(s) to use
  3. If the cortex agents tool is chosen, the client executes Cortex Agents through the MCP server
  4. The results are sent back to Claude
  5. Claude formulates a natural language response
  6. The response is displayed to you!

Common Errors

When the MCP client calls the MCP server, you may run into some of these common issues.

Error: Caused by SSLError(SSLCertVerificationError(1, "[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid...

Error: snowflake.connector.errors.InterfaceError: 250003 (08001): 404 Not Found: post https://xxxxx.snowflakecomputing.com:443/session/v1/login-request?request_id=b4e367d4-d8ac-48d3-8e44-96f42defa9c5&request_guid=4f63e07c-e42c-43b8-8f79-f6c577ee0d0e

In cortex_agents.py, update the payload included in the function run_cortex_agents to include more tools or different configurations (such as LLMs).

Congratulations! You've sucessfully built an MCP server for Cortex Agents. I hope you are inspired to use this MCP server you've built in interesting MCP clients!

What You Learned

Related Resources