CoCo CLI extensibility

CoCo CLI extensibility (확장성)

CoCo CLI는 사용자 지정 동작, 전문화된 에이전트, 수명 주기 훅, 외부 도구 통합으로 확장할 수 있어요. 이 주제는 네 가지 주요 확장 메커니즘을 다뤄요.

출처: CoCo CLI extensibility

본문

  • Skills — 대화에 도메인별 지식과 지침을 주입하는 Markdown 파일. 조직의 모범 사례, 코딩 표준, 전문화된 워크플로를 CoCo에 가르치는 데 사용.
  • Subagents — 특정 작업을 독립적으로 처리하는 자율적이고 전문화된 AI 에이전트. 병렬 실행, 집중된 전문성, 복잡한 다단계 워크플로를 가능하게 함.
  • Hooks — 주요 수명 주기 지점에서 CoCo의 동작을 가로채 맞춤화하는 스크립트. 도구 입력 검증, 작업 로깅, 정책 강제에 사용.
  • MCP (Model Context Protocol) — CoCo를 GitHub, Jira, 데이터베이스 같은 외부 도구·데이터 소스에 연결하는 공개 표준.

Skills

스킬은 전문화된 지침을 주입하고 추가 도구를 가능하게 해 도메인별 지식과 기능으로 CoCo를 확장해요.

스킬과 플러그인을 팀 또는 계정 전체와 공유할 수도 있어요. 자세한 내용은 Share skills and plugins를 참고해요.

스킬이란 무엇인가

스킬은 다음을 포함하는 markdown 파일이에요.

  • 도메인별 지침과 모범 사례
  • 스킬을 언제 사용할지
  • 예시 워크플로
  • 선택적 도구 구성

스킬을 호출하면 그 지침이 대화 컨텍스트에 주입돼요.

스킬 사용

/skill list를 실행해 사용 가능한 스킬을 나열하고, 이름으로 호출해 스킬을 대화에 로드해요.

스킬 위치

스킬은 여러 위치에서 로드되며, 높은 것에서 낮은 우선순위로 나열돼요.

위치 경로 범위
Project .cortex/skills/ 또는 .claude/skills/ 프로젝트
User ~/.snowflake/cortex/skills/ 또는 ~/.claude/skills/ 사용자
Global ~/.snowflake/cortex/skills/ 시스템
Session 일시 추가 세션
Remote git에서 복제 캐시
Bundled CoCo에 내장 시스템

모든 번들 스킬과 사용 방법의 전체 참조는 CoCo CLI bundled skills를 참고해요.

사용자 지정 스킬 만들기

스킬은 스킬 지침이 있는 SKILL.md 파일과 선택적 예시·템플릿을 포함한 디렉터리예요. 다음 위치 중 하나에서 스킬을 만들 수 있어요.

범위 경로
Project 프로젝트 디렉터리의 .cortex/skills/ 또는 .claude/skills/
Global ~/.snowflake/cortex/skills/
User ~/.claude/skills/

사용자 지정 스킬을 만들기 시작하려면:

  1. 스킬 디렉터리를 만들어요. 이 예시는 프로젝트 위치에 "my-skill"이라는 스킬 디렉터리를 만들어요.
mkdir -p .cortex/skills/my-skill
  1. 이 디렉터리에 SKILL.md를 만들고 스킬 지침을 추가해요. 이 예시는 기본 구조를 보여줘요.
---
name: my-skill
description: Brief description of what this skill does
tools:
- optional_tool_name
---

# When to Use

- Describe when this skill should be invoked
- List specific user intents or scenarios

# What This Skill Provides

Explain the capabilities and knowledge this skill adds.

# Instructions

Step-by-step guidance for the AI when this skill is active.

## Best Practices

- Best practice 1
- Best practice 2

## Common Patterns

### Pattern 1

Description and example.

### Pattern 2

Description and example.

# Examples

## Example 1: Basic Usage

User: $my-skill Do something Assistant: [Expected behavior]

## Example 2: Advanced Usage

User: $my-skill Complex task with @file.txt Assistant: [Expected behavior]
  1. $$ 명령을 사용해 스킬이 목록에 나타나는지 확인해요.
> $$

스킬이 나열되면 올바르게 로드되어 사용할 수 있는 거예요.

  1. 대화에서 스킬을 사용해요.
> $my-skill Test it out
사용자 지정 스킬 설정

각 스킬의 옵션은 SKILL.md 상단의 YAML frontmatter에 정의돼요. 다음 옵션이 지원돼요.

이 예시는 두 도구를 사용하는 스킬을 보여줘요.

---
name: database-admin
description: Database administration tasks
tools:
- sql_execute
- snowflake_object_search
---

SQL 실행 도구는 각 표면에서 다른 이름을 가져요. CoCo CLI는 그것을 sql_execute라고 부르며(CLI 1.1.8에서 snowflake_sql_execute에서 이름 변경), CoCo Desktop은 여전히 snowflake_sql_execute라고 부릅니다. 스킬이 두 표면 모두에서 작동해야 하면 두 이름을 모두 나열해요.

스킬의 tools: 목록의 도구 이름은 런타임 도구 ID이고 대소문자를 구분해요. bash, read, write 같은 내장 도구는 소문자예요.

스킬 모범 사례

효과적인 스킬을 작성하려면 다음 지침을 따라요.

  • 구체적으로: 명확한 지침이 더 나은 결과를 냄
  • 예시 제공: 예상 입력·출력 보여주기
  • 엣지 케이스 포함: 일반적인 오류·예외 처리
  • 집중 유지: 스킬 하나 = 도메인·기능 하나

스킬 관리

슬래시 명령 설명
/skill 대화형 스킬 매니저
/skill list 모든 스킬 나열
/skill sync <name> 전역 위치로 동기화
/skill add <path> 로컬 경로, Git 저장소, tarball, 또는 Snowflake 스테이지에서 스킬 추가
스킬 충돌

같은 스킬이 여러 지원 위치에 존재하고 내용이 다르면 충돌이 발생하고, 스킬 목록에 충돌 표시가 나타나요. /skill sync를 사용해 로컬 범위를 전역 범위로 동기화해 충돌을 해결해요.

스킬 구성

사용자 지정 스킬은 다른 스킬을 참조하거나 스킬을 파일 컨텍스트와 결합할 수 있어요.

> $code-review Review @src/auth.py following $security-guidelines

권장 스킬 공유

Snowflake는 Snowflake 카탈로그, Git 저장소, 또는 Snowflake 스테이지를 통해 스킬을 공유할 것을 권장해요.

Snowflake 카탈로그

Snowflake 카탈로그를 사용해 내장 거버넌스와 발견 가능성으로 계정 전체에서 스킬·플러그인을 공유해요. 이렇게 공유된 스킬·플러그인은 Snowsight의 AI & ML 아래 Skills and plugins 페이지에 나타나요. 자세한 내용은 Share skills and plugins를 참고해요.

Git 저장소

팀이 이미 Git에 버전 관리된 스킬을 저장할 때 Git 저장소를 사용해요. 저장소는 원하는 수의 스킬을 담을 수 있어요. 레이아웃은 로컬 스킬 구조와 일치해야 해요.

/skill add https://github.com/org/my-skills.git

Git 기반 스킬은 로컬에 캐시돼요.

Snowflake 스테이지

Snowflake를 통해 스킬을 배포하고 Snowflake 역할로 접근을 제어하려면 Snowflake 스테이지를 사용해요. 하나 이상의 로컬 스킬을 스테이지에 게시하고, 사용자가 스테이지에서 직접 스킬을 추가하게 하거나, 같은 공유 스테이지를 참조하는 프로필을 게시해요.

cortex skill publish ./my-skills --to-stage @MY_DB.MY_SCHEMA.MY_STAGE/skills/
cortex skill add @MY_DB.MY_SCHEMA.MY_STAGE/skills/
cortex profile publish data-analyst --skill-stage @MY_DB.MY_SCHEMA.MY_STAGE/skills/

내부 스테이지의 경우 스킬을 로드하는 사용자에게 READ를, 게시하는 사용자에게 WRITE를 부여해요. WRITE를 부여하려면 먼저 READ를 부여해요. 자세한 내용은 GRANT … TO ROLE과 Managing Snowflake stages를 참고해요.

Snowflake Git 저장소

외부 Git 저장소를 Snowflake에 미러링하려면 Snowflake Git 저장소를 만들고, 스킬 파일이 있는 저장소 브랜치 경로에서 스킬을 추가해요.

cortex skill publish --from-git https://github.com/org/my-skills.git \
  --to-repo MY_DB.MY_SCHEMA.MY_SKILLS_REPO
cortex skill add @MY_DB.MY_SCHEMA.MY_SKILLS_REPO/branches/main/

설정 요구사항은 Setting up Snowflake to use Git과 CREATE GIT REPOSITORY를 참고해요.

스킬 명령 참조

CLI 명령:

cortex skill list
cortex skill add <path>
cortex skill update <source>
cortex skill publish [path] --to-stage <stage>
cortex skill publish --from-git <url> --to-repo <repo>
cortex skill remove <path>

스킬 CLI 명령·옵션의 전체 목록은 cortex skill --help를 실행해요. 플러그인 CLI 명령은 cortex plugin --help를 실행해요.

슬래시 명령:

/skill list
/skill add <path>

스킬 문제 해결

스킬이 활성화되지 않음 — 스킬 목적과 관련된 구체적인 언어 사용. "semantic-view-optimization"과 같이 스킬을 명시적으로 언급. 가용성 확인: /skill list.

예기치 않은 동작 — 목표에 대한 더 많은 컨텍스트 제공. 더 구체적인 요청 시도. 피드백 제출: /feedback.

Subagents

하위 에이전트는 특정 작업을 독립적으로 처리하는 자율적이고 전문화된 AI 에이전트예요. 병렬 실행, 집중된 전문성, 복잡한 다단계 워크플로를 가능하게 해요.

하위 에이전트는:

  • 메인 대화와 독립적으로 실행
  • 자체 컨텍스트와 도구 접근 보유
  • 포그라운드 또는 백그라운드로 실행 가능
  • 특정 도메인·작업에 전문화

내장 하위 에이전트 유형

general-purpose

모든 도구에 접근하는 만능 에이전트. 다음에 가장 적합:

  • 복잡한 연구 작업
  • 다단계 코드 변경
  • 여러 도구가 필요한 작업
explore

빠른 코드베이스 탐색 전문가. 다음에 가장 적합:

  • 패턴으로 파일 찾기
  • 키워드로 코드 검색
  • 코드베이스 구조 이해
  • 빠른 정찰

Explore 에이전트가 검색하는 철저도를 지정할 수 있어요.

  • "quick": 기본 검색
  • "medium": 중간 탐색
  • "very thorough": 종합 분석
plan

복잡한 구현 계획을 설계·개요. 다음에 가장 적합:

  • 구현 전략 설계
  • 중요 파일 식별
  • 아키텍처 트레이드오프 평가
  • 단계별 계획 생성
feedback

구조화된 피드백 수집. 다음에 가장 적합:

  • 사용자 입력 수집
  • 구조화된 질문
  • 세션 피드백

하위 에이전트 실행

CoCo는 적절할 때 자동으로 하위 에이전트에 위임해요. 예를 들어 이 쿼리는 Explore 에이전트에 위임해요.

> Find all files that import the authentication module

특정 하위 에이전트 유형을 이름으로 명시적으로 요청할 수도 있어요.

> Use an Explore agent to find all database query definitions
> Use the Explore agent to find all API endpoint definitions
> Launch a Plan agent to design the authentication refactor

여러 하위 에이전트를 병렬로 실행해 작업의 다른 측면을 다루도록 요청할 수도 있어요.

> In parallel, search for all test files and all config files

에이전트는 내가 계속 작업하는 동안 백그라운드에서 실행될 수 있어요.

> Run a background agent to refactor all the test files

에이전트는 즉시 시작하고 추적용 에이전트 ID를 반환해요. 에이전트가 완료되면 ID를 사용해 출력을 검색할 수 있어요.

> Get the output from agent abc1234

실행 중인 모든 하위 에이전트의 상태를 모니터링하려면 /agents 명령(Ctrl-B)을 사용해 백그라운드 프로세스 뷰어를 열어요. ID로 실행 중인 에이전트를 멈추거나 /agents 인터페이스로 멈출 수 있어요.

> kill agent abc1234

멈춘 에이전트는 실행을 멈추지만 컨텍스트를 무기한 유지해요. ID를 사용해 멈춘 에이전트를 재개할 수 있어요.

> Resume agent abc1234 and continue from where it left off

에이전트 유형

자율(Autonomous) — 자율 에이전트는 사용자 상호작용 없이 실행돼요. 에이전트는:

  • 독립적으로 완료
  • 질문을 위해 절대 차단하지 않음
  • 잘 정의된 작업에 적합

비자율(Non-Autonomous) — 비자율 에이전트는 실행을 일시 중지해 사용자에게 질문할 수 있어요. 에이전트는:

  • 명확화 질문을 할 수 있음
  • 권한을 대화형으로 요청할 수 있음
  • 안내가 필요한 작업에 적합

사용자 지정(Custom) — 사용자 지정 에이전트는 전문화된 프롬프트와 구성이 있는 사용자 정의 하위 에이전트예요. 사용자 지정 스킬과 유사하게, 특정 도메인이나 워크플로에 맞춘 에이전트를 Markdown 파일로 만들어요.

사용자 지정 하위 에이전트 만들기

사용자 지정 하위 에이전트는 YAML front matter가 있는 Markdown 파일에 정의돼요. Front matter는 에이전트의 이름, 설명, 도구 접근, 모델을 지정해요. 본문은 에이전트 동작을 안내하는 시스템 프롬프트를 담아요.

사용자 지정 에이전트 Markdown 파일을 세 위치 중 하나에 저장할 수 있어요.

범위 경로
Project .cortex/agents/ 또는 .claude/agents/
Global ~/.snowflake/cortex/agents/
User ~/.claude/agents/

에이전트 정의의 형식은 다음과 같아요.

---
name: my-agent
description: What this agent specializes in
tools:

- bash
- read
- write

model: claude-sonnet-4-5
---

# System Prompt

You are a specialized agent for [domain].

## Your Responsibilities

1. Task 1
2. Task 2

## Guidelines

- Guideline 1
- Guideline 2

## Output Format

Describe expected output format.
예시: Test Runner 에이전트

다음 Markdown 파일은 테스트를 실행하고 결과를 요약하는 사용자 지정 Test Runner 에이전트를 정의해요.

---
name: test-runner
description: Runs tests and reports results
tools:
- bash
- read
- grep
---

# Test Runner Agent

You run tests and provide clear reports of the results.

## Process

1. Identify the test framework (pytest, jest, go test, etc.)
2. Run appropriate test command
3. Parse and summarize results
4. Highlight failures with relevant code context

## Output Format

## Test Results Summary

- Total: X
- Passed: Y
- Failed: Z

## Failures

### Test Name

- File: path/to/file.py
- Error: Description
- Relevant code snippet
에이전트 구성

사용자 지정 에이전트의 구성은 Markdown 파일의 YAML front matter에 지정돼요.

도구 접근 — 에이전트가 접근할 수 있는 도구를 지정할 수 있어요:

tools:
- "*"           # All tools
- bash          # Specific tools
- read
- write

tools: 목록의 도구 이름은 런타임 도구 ID이며 소문자예요(bash, read, write, grep, glob 같은). Bash 같은 대문자 이름은 해석되지 않아요. 인식되지 않는 항목은 조용히 건너뛰어지므로, 목록 전체가 대문자인 에이전트는 도구 없이 시작하고 오류를 보고하지 않아요. 에이전트가 파일을 읽거나 명령을 실행할 수 없는 것처럼 행동하면 tools: 목록의 대소문자를 먼저 확인해요.

모델 선택 — 특정 에이전트에 모델을 고를 수 있어요. 이는 세션의 기본 모델을 오버라이드해요.

model: claude-sonnet-4-5   # Specific model
model: auto                # Cost-optimized

워크트리 격리

에이전트는 격리된 git 워크트리 또는 브랜치에서 실행될 수 있어요. 워크트리 격리를 요청하면 CoCo CLI가 에이전트가 작동할 별도의 git 워크트리를 만들어요. 이를 통해 여러 에이전트가 충돌하는 변경 없이 병렬로 실행될 수 있고, 나중에 정리하기 쉬워요. 격리된 워크트리는 탐색과 실험에 특히 유용해요. 에이전트가 만든 git 브랜치는 agent/<agentId>로 이름이 지정돼요.

워크트리 격리를 사용하려면 프롬프트에 포함하면 돼요.

> Run a background agent with worktree isolation to implement feature X

Swarm 패턴

복잡한 작업의 다른 측면을 병렬로 다루는 에이전트 swarm을 시작할 수 있어요. 각 에이전트는 독립적으로 작업하고, 모든 에이전트가 끝나면 결과가 집계돼요. 모든 유형의 에이전트가 swarm에 참여할 수 있어요.

Swarm의 사용 사례:

  • 코드 분석: 여러 에이전트가 다른 측면 분석
  • 리팩터링: 병렬 에이전트가 다른 파일 처리
  • 테스트: 에이전트가 다른 테스트 스위트 실행
  • 문서화: 에이전트가 다른 구성 요소 문서화

Swarm을 만들려면 시작할 다른 에이전트들을 설명하면 돼요.

> Launch a swarm of agents:
> 1. Explore agent to find all database queries
> 2. Explore agent to find all API endpoints
> 3. Explore agent to find all test files

하위 에이전트 모범 사례

하위 에이전트를 다음에 사용해요.

  • 복잡한 작업: 병렬 실행을 위해 하위 작업으로 분해
  • 탐색: 코드베이스 검색에 Explore 에이전트 사용
  • 계획: 주요 변경 전에 Plan 에이전트 사용
  • 백그라운드 작업: 관심이 필요 없는 장기 실행 작업

하위 에이전트가 이상적이지 않은 경우:

  • 단순 쿼리: 직접 도구가 더 빠름
  • 단일 파일 편집: 메인 에이전트가 더 효율적
  • 대화형 작업: 즉시 피드백이 필요할 때

상세한 프롬프트가 일반적으로 더 효과적이에요.

| 좋음 | Find all Python files that contain database queries and list them with line numbers | | 더 좋음 | Use the Explore agent (very thorough) to find all Python files containing database queries. For each file, extract the query patterns and identify potential SQL injection risks. |

활성 하위 에이전트 보기

/agents 명령 — CoCo 세션에서 /agents 명령을 실행해 대화형 에이전트 뷰어를 열어요. 이 인터페이스는 모든 실행 중인 에이전트, 그 유형, 상태, 출력 미리 보기를 보여줘요.

백그라운드 프로세스 뷰어 — CoCo CLI 세션에서 Ctrl-B를 눌러 다음을 봐요.

  • 모든 백그라운드 프로세스
  • 에이전트 세션
  • Bash 프로세스

에이전트 한도

CoCo CLI의 하위 에이전트에 다음 한도가 적용돼요.

  • 최대 50개 동시 백그라운드 에이전트
  • 에이전트는 세션 권한 상속
  • 백그라운드 에이전트는 다른 백그라운드 에이전트를 생성할 수 없음

Hooks

훅은 주요 수명 주기 지점에서 CoCo의 동작을 가로채고 사용자 지정할 수 있게 해줘요. 훅은 이벤트에 응답해 실행되는 프롬프트 또는 셸 스크립트예요.

  • 도구 사용 전: 도구 입력 검증·수정
  • 도구 사용 후: 컨텍스트 추가·결과 로깅
  • 사용자 입력 시: 세션 컨텍스트 주입
  • 세션 이벤트 시: 초기화·정리

훅 이벤트

다음 이벤트가 훅을 트리거할 수 있어요.

이벤트 설명 차단 가능
PreToolUse 도구 실행 전 예
PostToolUse 도구 실행 후 아니요
PermissionRequest 권한이 필요할 때 예
UserPromptSubmit 사용자가 프롬프트 제출 시 아니요
SessionStart 세션 시작 시 아니요
SessionEnd 세션 종료 시 아니요
PreCompact 컨텍스트 압축 전 아니요
Stop 사용자가 중지할 때 아니요
SubagentStop 하위 에이전트 중지 시 아니요
Notification 시스템 알림 시 아니요
Setup 초기화 중 아니요

훅 구성

훅은 설정 파일에 구성되며, 어떤 구성 디렉터리든 될 수 있어요(높은 것에서 낮은 우선순위로 나열).

위치 경로
Local .claude/settings.local.json 또는 .cortex/settings.local.json
Project .claude/settings.json 또는 .cortex/settings.json
User ~/.claude/settings.json
Global ~/.snowflake/cortex/hooks.json

훅은 JSON 형식으로 정의되며, 이벤트, 도구 매처, 훅 동작을 지정해요. 사전 도구 사용 훅의 간단한 예시는 다음과 같아요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/validate-bash.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

두 가지 훅 유형이 지원돼요: command 훅과 prompt 훅.

  • Command 훅은 셸 명령이나 스크립트를 실행해요.
{
  "type": "command",
  "command": "bash /path/to/script.sh",
  "timeout": 60,
  "enabled": true
}
  • Prompt 훅은 언어 모델용 자연어 프롬프트로 평가돼요.
{
  "type": "prompt",
  "prompt": "Is this command safe? $ARGUMENTS",
  "timeout": 30
}

특정 도구에서만 훅을 실행하려면 matcher 필드에 도구 이름이나 패턴을 넣어요. 예를 들어 모든 SQL 도구를 일치시키려면 "matcher": ".*sql.*"를 사용해요. 정규식으로 여러 도구를 일치시킬 수 있어요.

패턴은 대소문자 구분인 런타임 도구 이름과 일치해요. 내장 도구 이름은 소문자이므로 bash는 일치하고 Bash는 일치하지 않아요.

패턴 일치
* 모든 도구
bash bash만
edit|write edit 또는 write
mcp__.* 모든 MCP 도구
notebook.* notebook_edit_cell, notebook_run_cell

훅 스크립트 작성

훅 스크립트는 표준 입력으로 JSON 입력을 받고 표준 출력으로 JSON 출력을 반환해요. 출력에는 작업이 허용되는지 거부되는지 나타내는 필드가 포함돼요. 선택적으로 훅 스크립트는 수정된 도구 입력 버전을 돌려줄 수 있어요.

샘플 입력:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.json",
  "cwd": "/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "bash",
  "tool_input": {
    "command": "ls -la"
  }
}

샘플 출력:

{
  "decision": "allow",
  "systemMessage": "Note: This operation was validated.",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "ls -la --color=never"
    }
  }
}

반환 코드는 작업을 차단할지 나타내요.

  • 0: 차단하지 않음
  • 2: 차단

이 정보는 아래처럼 JSON 출력의 일부로도 반환될 수 있어요.

{
  "decision": "block",
  "reason": "Operation not allowed"
}

훅 스크립트에서 사용 가능한 환경 변수는 다음과 같아요.

변수 설명
CORTEX_PROJECT_DIR 프로젝트 디렉터리 경로
CORTEX_CODE_REMOTE 웹 컨텍스트면 "true"
CORTEX_ENV_FILE 영구 env 파일 경로

훅 예시

다음 예시는 일반적인 훅 사용 사례에 대한 가능한 출력을 보여줘요.

도구 입력 수정
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "modified command"
    }
  }
}
컨텍스트 추가
{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Note: File was recently modified."
  }
}
시스템 메시지 표시
{
  "systemMessage": "Warning: This operation may take a while."
}
권한 결정
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved by policy"
  }
}
원격 훅

다음처럼 Git 저장소의 스크립트를 참조할 수 있어요.

{
  "type": "command",
  "command": "bash",
  "source": {
    "source": "github:org/hooks-repo/scripts/validate.sh",
    "ref": "main"
  }
}

훅 모범 사례

  • 훅을 빠르게 유지: 타임아웃 기본값 60초
  • 오류를 우아하게 처리: 불확실하면 exit 0 반환
  • 디버깅용 로깅: 문제 해결을 위해 파일로 기록
  • 매처 사용: 특정 도구를 대상으로, 전부가 아니라
  • 철저히 테스트: 훅 매니저로 동작 검증

Model Context Protocol (MCP)

Model Context Protocol(MCP)로 CoCo CLI를 외부 도구·데이터 소스에 연결할 수 있어요. MCP는 AI 에이전트를 GitHub, Jira, 데이터베이스 같은 외부 도구에 연결하는 공개 표준이에요. 구성되면 MCP 서버가 내장 기능을 넘어서는 호스팅 도구에 CoCo를 접근하게 해줘요.

전송 유형

CoCo는 세 가지 MCP 전송 유형을 지원해요.

유형 사용 사례 연결
stdio 로컬 도구, CLI 래퍼 stdin/stdout 하위 프로세스
http 웹 서비스, API HTTP 요청
sse 실시간 서비스 Server-Sent Events

OAuth를 사용해 HTTP MCP 서버에 인증할 수 있어요. OAuth용으로 구성된 서버에 처음 연결하면 CoCo CLI가 브라우저 창을 열고 사용자가 인증해요. 결과 토큰은 ~/.snowflake/cortex/mcp_oauth/에 저장되고 필요에 따라 자동으로 새로고침돼요. 다음은 샘플 OAuth 구성이에요.

{
   "oauth": {
      "client_id": "pre-registered-client-id",
      "client_name": "My Client",
      "redirect_port": 8585,
      "scope": "openid mcp read write",
      "authorization_server_url": "https://auth.example.com"
   }
}

MCP 서버 관리

대화형 CoCo CLI 세션에서 /mcp 명령을 실행해 대화형 MCP 상태 뷰어를 열 수 있어요. cortex mcp 명령으로 명령줄에서 MCP 서버 구성을 관리해요.

명령 설명
cortex mcp add 새 서버 추가(아래 참고)
cortex mcp list 구성된 서버 나열
cortex mcp get <server> 특정 서버 상세 정보
cortex mcp remove <server> 서버 제거
cortex mcp start <server> 서버 상태와 사용 가능한 도구 확인
서버 추가

cortex mcp add 명령은 서버 구성 옵션을 받아요.

cortex mcp add <name> <command> [args...]

옵션:

--transport, -t    Transport type (stdio, http, sse)
--type             Alias for --transport
--env, -e          Environment variable (KEY=value)
--header, -H       HTTP header
--timeout          Connection timeout in ms

참고

MCP 도구는 아래 형식으로 충돌을 피하기 위해 네임스페이스 처리돼요.

mcp__{server-name}__{tool-name}

예를 들어 github 서버의 search라는 도구는 mcp__github__search라는 이름이 부여돼요.

MCP 구성

MCP 서버 구성은 mcpServers 키 아래 ~/.snowflake/cortex/mcp.json에 저장돼요. 다음 예시는 단일 MCP 서버가 있는 구성 파일의 구조를 보여줘요.

{
   "mcpServers": {
      "server-name": {
         "type": "stdio",
         "command": "command-to-run",
         "args": ["arg1", "arg2"]
      }
   }
}
환경 변수

\${VAR} 또는 $VAR 구문으로 환경 변수의 값을 구성 파일에 삽입해요.

{
"mcpServers": {
   "my-server": {
      "type": "http",
      "url": "https://api.example.com",
      "headers": {
      "Authorization": "Bearer ${MY_API_TOKEN}"
      }
   }
}

중요

자격 증명에 환경 변수를 사용하는 것이 모범 사례예요. mcp.json에 토큰을 절대 하드코딩하지 마요. ~/.bashrc 또는 ~/.zshrc 같은 셸 프로필에 다음과 같은 줄을 추가해요.

export GITHUB_TOKEN="your_token_here"
명령줄에서 구성

명령줄에서 MCP 서버를 추가하려면 cortex mcp add 명령을 사용해요. 예:

동작 명령
stdio 서버 추가 cortex mcp add git-server uvx mcp-server-git
HTTP 서버 추가 cortex mcp add api-server https://api.example.com --type http
환경 변수와 함께 추가 cortex mcp add my-server npx my-mcp-server -e API_KEY=secret
헤더와 함께 추가 cortex mcp add my-server https://api.example.com -H "Authorization: Bearer ***"

MCP 도구 사용

구성되면 MCP 도구는 CoCo CLI 세션에서 자동으로 사용 가능해요. 자연어 명령으로 호출해요.

Show me recent GitHub pull requests
Create a Jira ticket for this bug
Query the PostgreSQL database for user activity

권한은 첫 사용에 요청돼요. ~/.snowflake/cortex/permissions.json에 기본값을 구성해요.

{
  "allow": ["mcp__github__read_file", "mcp__github__list_repos"],
  "deny": ["mcp__github__delete_repo"]
}

샘플 MCP 구성

다음 예시는 일반적인 사용 사례의 MCP 서버 구성을 보여줘요.

Git 서버(stdio)
{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}
OAuth가 있는 HTTP API
{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "client_id": "my-client-id",
        "redirect_port": 8585,
        "scope": "openid mcp"
      }
    }
  }
}
헤더가 있는 SSE 서버
{
  "mcpServers": {
    "realtime": {
      "type": "sse",
      "url": "https://realtime.example.com/events",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      },
      "timeout": 30000
    }
  }
}
Sourcegraph 통합
{
  "mcpServers": {
    "sourcegraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourcegraph/mcp-server"],
      "env": {
        "SRC_ACCESS_TOKEN": "${SOURCEGRAPH_TOKEN}",
        "SRC_ENDPOINT": "https://sourcegraph.company.com"
      }
    }
  }
}

MCP 문제 해결

서버가 연결되지 않음 — 세션 중 /mcp로 나열되는지 확인. cortex mcp start <server>로 연결 테스트. 환경 변수에 자격 증명이 올바르게 설정되었는지 확인. cat ~/.snowflake/cortex/logs/mcp.log로 단서를 위해 로그 검토.

도구가 나타나지 않음 — cortex mcp list를 실행해 구성 확인. 도구 이름이 유효한지 확인(영숫자, 밑줄, 하이픈만). 도구 이름이 64자 미만인지 확인.

OAuth 문제 — 캐시된 토큰 지우기: rm ~/.snowflake/cortex/mcp_oauth/{server}*. 새 OAuth 흐름을 트리거하려면 재연결. 리다이렉트 포트 사용 가능 확인(기본 8585).

환경 변수가 확장되지 않음 — $VAR보다 \${VAR} 구문(중괄호) 사용. 셸에서 변수가 설정되었는지 확인(echo $VAR). 변수 이름의 오타 확인.

MCP 모범 사례

  • 설명적인 서버 이름 사용: 도구 네임스페이싱을 명확하게
  • 적절한 타임아웃 설정: 도구 목록 기본 10분
  • 자격 증명 보안: 하드코딩된 시크릿이 아니라 환경 변수 사용
  • 연결 테스트: 서버에 의존하기 전에 cortex mcp start 사용

더 알아보기