Architecture Reference

MCP + Skills Architecture

How Cortex Code connects to a partner's remote MCP server and how Skills layer domain expertise on top of MCP tool access for powerful integrations.

← Back to Resources
Core Concept
Why Skills + MCP Together
MCP gives the agent access to partner tools. A Skill gives the agent expertise on how to use them. Without a skill, the agent can still call MCP tools — but a skill ensures it follows your exact workflow, respects approval gates, and handles edge cases correctly.

◆ MCP (Tool Access)

Connects Cortex Code to the partner's remote server at runtime.

  • Exposes tools the agent can discover and call
  • JSON-RPC 2.0 protocol over HTTPS
  • Auth via headers (Bearer, API keys) or OAuth
  • Config: ~/.snowflake/cortex/mcp.json
  • Tool naming: mcp__<server>__<tool>

◈ Skills (Domain Expertise)

Guides how and when the agent uses those tools.

  • Structured workflow with steps, goals, and actions
  • Mandatory stopping points for user approval
  • References MCP tools by name in instructions
  • Invoked with $skill-name or auto-triggered
  • Created with $skill-development
Architecture
Partner MCP Integration with Skills
Cortex Code acts as an MCP Host, connecting to a partner's remote MCP server over HTTPS. A custom Skill provides the domain knowledge that guides the agent on how and when to use the partner's MCP tools. The Skill orchestrates; MCP executes. 
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#E8F7FC',
    'primaryTextColor': '#0D2B3E',
    'primaryBorderColor': '#29B5E8',
    'secondaryColor': '#F4FBFE',
    'tertiaryColor': '#EEF2F5',
    'lineColor': '#29B5E8',
    'textColor': '#1A2530',
    'fontSize': '13px'
  },
  'flowchart': { 'nodeSpacing': 40, 'rankSpacing': 60, 'padding': 20 }
}}%%
flowchart LR
  DEV["Developer"]

  subgraph HOST["Cortex Code"]
    direction TB
    SKILL["Skill: $partner-sync"]
    AGENT["AI Agent"]
    CLIENT["MCP Client"]
    SKILL -.- AGENT
    AGENT --> CLIENT
  end

  subgraph REMOTE["MCP Server"]
    direction TB
    TOOLS["Tools"]
  end

  subgraph BACKEND["Backend"]
    direction TB
    API["REST APIs"]
    DB["Databases"]
    SVC["Services"]
  end

  DEV -->|"prompt"| SKILL
  CLIENT <-->|"JSON-RPC over HTTPS"| TOOLS
  TOOLS --> API
  TOOLS --> DB
  TOOLS --> SVC
  AGENT -->|"response"| DEV

  style DEV fill:#29B5E8,stroke:#11567F,color:#FFFFFF
  style HOST fill:#0D2B3E,stroke:#29B5E8,color:#FFFFFF
  style SKILL fill:#7254A3,stroke:#9B8EC4,color:#FFFFFF
  style AGENT fill:#11567F,stroke:#29B5E8,color:#FFFFFF
  style CLIENT fill:#1B6D9C,stroke:#29B5E8,color:#FFFFFF
  style REMOTE fill:#E8F7FC,stroke:#29B5E8,color:#0D2B3E
  style TOOLS fill:#FFFFFF,stroke:#29B5E8,color:#0D2B3E
  style BACKEND fill:#FFF8F0,stroke:#FF9F36,color:#0D2B3E
  style API fill:#FFFFFF,stroke:#FF9F36,color:#2D3842
  style DB fill:#FFFFFF,stroke:#FF9F36,color:#2D3842
  style SVC fill:#FFFFFF,stroke:#FF9F36,color:#2D3842
Protocol Flow
Skill-Guided MCP Tool Invocation
When a developer triggers the $partner-sync skill, Cortex Code follows the skill's workflow to discover, validate, and invoke the partner's MCP tools in sequence. The skill provides the guardrails; MCP provides the transport. 
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'actorBkg': '#11567F',
    'actorTextColor': '#FFFFFF',
    'actorBorder': '#29B5E8',
    'activationBkgColor': '#E8F7FC',
    'activationBorderColor': '#29B5E8',
    'signalColor': '#0D2B3E',
    'signalTextColor': '#0D2B3E',
    'noteBkgColor': '#FFF8F0',
    'noteTextColor': '#0D2B3E',
    'noteBorderColor': '#FF9F36',
    'sequenceNumberColor': '#FFFFFF',
    'fontSize': '13px'
  },
  'sequence': { 'mirrorActors': false, 'messageMargin': 35 }
}}%%
sequenceDiagram
  participant Dev as Developer
  participant CoCo as Cortex Code
  participant MCP as Partner MCP Server
  participant API as Partner Backend

  Dev->>CoCo: "$partner-sync orders to analytics"
  activate CoCo
  Note over CoCo: Skill loaded: workflow begins

  Note over CoCo,MCP: Step 1 — Discover datasets
  CoCo->>MCP: tools/call("list_datasets")
  MCP->>API: GET /datasets
  API-->>MCP: [{id: "ds_17", name: "analytics"}, ...]
  MCP-->>CoCo: datasets list

  Note over CoCo,MCP: Step 2 — Validate schema
  CoCo->>MCP: tools/call("validate_schema", {source, target})
  MCP->>API: POST /validate
  API-->>MCP: {compatible: true, warnings: []}
  MCP-->>CoCo: schema validated

  CoCo-->>Dev: "Schema compatible. Push 12,450 rows?"
  Note over Dev,CoCo: Stopping point — user approval

  Dev->>CoCo: "Yes, go ahead"

  Note over CoCo,MCP: Step 3 — Push data
  CoCo->>MCP: tools/call("push_data", {source, target})
  MCP->>API: POST /sync
  API-->>MCP: {rows: 12450, status: "complete"}
  MCP-->>CoCo: sync result

  CoCo-->>Dev: "Synced 12,450 rows to analytics dataset"
  deactivate CoCo
Getting Started
Connecting to a Partner's Remote MCP Server
Partners host MCP servers on their own infrastructure, exposing tools via the standard MCP protocol over HTTPS. Authentication supports Bearer tokens, API keys, and OAuth. Here are two ways to configure the connection in Cortex Code.
1

Add via CLI

The quickest way to connect. The cortex mcp add command registers the remote server and writes the configuration to ~/.snowflake/cortex/mcp.json.

# Add a partner's remote MCP server cortex mcp add partner-analytics \ -H "Authorization: Bearer ${PARTNER_API_TOKEN}" \ https://mcp.partner-platform.com/v1/mcp # Verify it's connected cortex mcp list # Or use the interactive manager /mcp

Tools become available as mcp__partner-analytics__<tool_name> in Cortex Code. Use ${VAR} syntax for secrets so they expand from your environment at runtime.

2

Configure via mcp.json

For repeatable setup or when configuring multiple servers, edit the config file directly. Environment variable expansion (${VAR}) keeps secrets out of the file.

~/.snowflake/cortex/mcp.json
{ "mcpServers": { "partner-analytics": { "url": "https://mcp.partner-platform.com/v1/mcp", "headers": { "Authorization": "Bearer ${PARTNER_API_TOKEN}" } } } }

You can also use OAuth for authentication. The headers field supports any standard HTTP header, including OAuth Bearer tokens obtained from your identity provider. Use ${VAR} syntax so secrets expand from your environment at runtime.

Restart Cortex Code or use /mcp to reload after editing.

Full Example
Custom Skill for Partner MCP Integration
This skill follows Cortex Code's $skill-development best practices: name and description in frontmatter (description includes trigger keywords), structured workflow with goals and actions per step, mandatory stopping points before destructive operations, and an output section.

.cortex/skills/partner-sync/SKILL.md

--- name: partner-sync description: | Sync Snowflake tables to Partner Analytics Platform via MCP. Use when: syncing data to partner, pushing tables, validating schema compatibility, checking sync status. Triggers: partner sync, push to partner, sync pipeline, partner data, export to partner. --- # Partner Data Sync ## Prerequisites - MCP server partner-analytics must be configured - Verify with: cortex mcp list - If missing, add: cortex mcp add partner-analytics \ -H "Authorization: Bearer ${PARTNER_API_TOKEN}" \ https://mcp.partner-platform.com/v1/mcp ## Workflow ### Step 1: Gather Information **Goal:** Identify the source table and target dataset. **Actions:** 1. **Ask** the user which Snowflake table to sync. 2. **Call** mcp__partner-analytics__list_datasets to show available target datasets. 3. **Ask** user to confirm the target dataset. **Output:** Source table ref + target dataset ID. ### Step 2: Validate Compatibility **Goal:** Ensure schemas are compatible before pushing data. **Actions:** 1. **Call** mcp__partner-analytics__validate_schema with the source table schema and target dataset ID. 2. **Present** the validation result to the user. - If warnings exist, list them clearly. - If incompatible, explain why and stop. ### Step 3: Push Data **Goal:** Sync rows from Snowflake to the partner platform. ⚠️ MANDATORY STOPPING POINT Confirm with user before pushing. Show: source table, target dataset, row count, and any schema warnings. Never push without explicit user approval. **Actions:** 1. **Call** mcp__partner-analytics__push_data with the source table reference and target dataset ID. 2. **Call** mcp__partner-analytics__get_sync_status to verify the sync completed successfully. 3. **Report** final row count and status to the user. ## Stopping Points - ✋ After Step 1 — confirm target dataset selection - ✋ After Step 2 — if schema warnings found - ✋ Before Step 3 — always get push approval ## Output Summary including: source table, target dataset, rows synced, sync status, and any warnings encountered.