CoCo CLI Model Context Protocol

CoCo CLI Model Context Protocol (MCP) support (MCP 지원)

CoCo CLI는 Model Context Protocol(MCP)을 구현해요. AI 에이전트를 GitHub, Jira, 내부 API, 데이터베이스 같은 외부 도구와 데이터 소스에 연결하는 공개 표준이에요. CoCo에 MCP 서버를 추가하면 그 도구들이 에이전트에게 자동으로 사용 가능해져요. 코드 변경이 필요 없어요.

출처: CoCo CLI Model Context Protocol (MCP) support

본문

이 주제는 MCP 서버를 추가·관리하는 방법, 전체 구성 스키마, 자격 증명 처리, 관리자 제어를 다뤄요.

전송 유형

CoCo는 세 가지 MCP 전송 유형을 지원해요. 내 서버에 맞는 전송을 골라요.

유형	사용 사례	CoCo가 연결하는 방식
stdio	로컬 도구, CLI 래퍼, 언어별 MCP 서버	하위 프로세스 생성, stdin/stdout으로 통신
http	웹 서비스, 호스팅 API	Streamable HTTP 요청
sse	실시간 스트리밍 서비스	HTTPS를 통한 Server-Sent Events

MCP 서버 관리

명령줄에서 cortex mcp로 MCP 서버를 관리하거나, CoCo 세션에서 대화형으로 /mcp 슬래시 명령으로 관리할 수 있어요.

명령 참조

명령	설명
`cortex mcp add <name> <commandOrUrl> [args...]`	새 MCP 서버 등록. 서버 추가에서 플래그 참고.
`cortex mcp list`	전송, URL 또는 명령, 마스킹된 자격 증명 키와 함께 모든 구성 서버 나열.
`cortex mcp get <name>`	OAuth 필드를 포함한 단일 서버의 상세 구성 표시.
`cortex mcp remove <name>`	구성에서 서버 제거 및 저장된 자격 증명 삭제.
`cortex mcp start`	모든 구성 서버에 연결하고 연결·실패 수 보고. 서버 로드에 최대 300초 대기.

대화형 관리

CoCo CLI 세션에서 /mcp를 실행해 대화형 MCP 상태 뷰어를 열어요. 뷰어는 다음을 표시해요.

각 서버의 이름, 전송 유형, 연결 상태(connecting, connected, reconnecting, failed, not_started)
각 연결 서버가 노출하는 도구 수
실패한 서버가 보고한 마지막 오류
구성 파일을 편집하지 않고 개별 서버를 켜거나 끄는 토글 버튼

서버 추가

명령줄에서 cortex mcp add로 새 MCP 서버를 등록해요.

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

플래그:

플래그	설명
`-t, --transport`(별칭 `--type`)	전송 유형: stdio, http, 또는 sse. 기본값 stdio. 전송이 URL 패턴과 일관되지 않으면 CoCo가 경고.
`-e, --env <KEY=value>`	하위 프로세스용 환경 변수 설정(stdio 전용). 반복 가능.
`-H, --header <Header: value>`	HTTP 헤더 설정(http와 sse 전용). 반복 가능.
`--timeout <ms>`	도구 호출 타임아웃(밀리초).

일반적인 예:

동작	명령
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-api https://api.example.com -H "Authorization: Bearer ***"`

-e 또는 -H로 전달된 민감한 값은 첫 연결 시 OS 키체인으로 마이그레이션돼요(자격 증명 저장 참고).

구성 파일

MCP 서버는 다음에 구성돼요.

~/.snowflake/cortex/mcp.json

최상위 키는 mcpServers예요. 각 항목은 서버 이름으로 키가 매겨져요.

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

서버 필드

필드	유형	설명
`type`	string	필수. stdio, http, sse 중 하나.
`command`	string	stdio 전송용 실행 파일.
`args`	문자열 배열	command에 전달되는 인자.
`cwd`	string	stdio 하위 프로세스용 작업 디렉터리.
`url`	string	http와 sse 전송용 엔드포인트 URL.
`env`	object	stdio 하위 프로세스용 환경 변수. 첫 사용 시 키체인으로 마이그레이션.
`headers`	object	http와 sse 전송용 HTTP 헤더. 첫 사용 시 키체인으로 마이그레이션.
`timeout`	number	도구 호출 타임아웃(밀리초). 기본 60,000(60초). `COCO_MCP_TOOL_TIMEOUT_MS` 환경 변수로 전역 오버라이드도 가능.
`oauth`	object	http 전송용 OAuth 2.0 구성. OAuth 인증 참고.

환경 변수 확장

CoCo는 연결 전에 mcp.json의 모든 필드에서 환경 변수를 확장해요. 세 가지 구문이 지원돼요.

구문	동작
`\${VAR}`	VAR 값으로 대체. VAR이 설정되지 않았으면 리터럴 `\${VAR}` 보존.
`\${VAR:-default}`	VAR이 설정되면 VAR로, 그렇지 않으면 default로 대체.
`$VAR`	`\${VAR}`의 짧은 형태.

중요

자격 증명에는 환경 변수를 사용해요. mcp.json에 토큰이나 시크릿을 하드코딩하지 마요. 셸 프로필(~/.bashrc, ~/.zshrc)에서 민감한 값을 export 해 소스 제어에 체크되지 않게 해요.

export GITHUB_TOKEN="your_token_here"

구성 우선순위

CoCo는 여러 소스에서 MCP 서버를 다음 순서로 병합해요(이름이 충돌하면 나중 소스가 이기며, 플러그인은 예외).

managed settings 강제 파일의 관리자 강제 서버.
활성 Snowflake 연결에 선언된 연결 프로필 서버.
~/.snowflake/cortex/mcp.json의 사용자 서버(관리자가 사용자 MCP 서버를 허용하는 경우에만).
설치된 플러그인이 선언한 플러그인 서버(관리자가 사용자 MCP 서버를 비활성화하면 건너뜀). 플러그인 서버는 더 높은 수준에서 구성된 기존 서버를 절대 덮어쓰지 않아요.
관리자 URL 허용 목록. 병합 후 managed settings가 허용하지 않는 url의 서버는 조용히 제거돼요.

강제 정책에 대한 자세한 내용은 managed settings를 참고해요.

도구 이름과 권한

MCP 도구는 서버 이름으로 네임스페이스되어 두 서버가 같은 이름의 도구를 충돌 없이 노출할 수 있어요. 구성된 도구 이름 형태:

mcp__<server-name>__<tool-name>

예를 들어 github 서버가 노출하는 search라는 도구는 에이전트에게 mcp__github__search로 보여요.

도구 이름은 64자로 제한되고 영숫자, 밑줄, 하이픈만 포함해야 해요.

권한

MCP 도구는 표준 CoCo 권한 시스템에 참여해요. 기본 권한 결정은 다음에 구성할 수 있어요.

~/.snowflake/cortex/permissions.json

개별 도구를 완전한 구성 이름으로 일치시키거나, 와일드카드 패턴으로 서버의 모든 도구를 일치시킬 수 있어요.

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

런타임 시 권한도 첫 사용에 요청되고 세션 동안 기억될 수 있어요.

자격 증명 저장

서버가 env, headers, 또는 OAuth로 추가되거나 구성되면, CoCo는 첫 연결 시 민감한 값을 mcp.json에서 OS 키체인으로 마이그레이션해요. mcp.json 파일은 그 필드들이 제거된 채로 다시 쓰여요.

자격 증명은 토큰, OAuth 클라이언트 등록, 헤더, 환경 변수를 담은 통합 blob으로 mcp_oauth_<server-name> 키체인 항목 아래에 저장돼요.
cortex mcp list와 cortex mcp get은 키 이름을 표시하지만 절대 시크릿 값을 표시하지 않아요.
cortex mcp remove는 구성 항목과 키체인 항목을 모두 제거해요.

OS 키체인을 사용할 수 없으면(예: 헤드리스 컨테이너), 자격 증명 저장은 정상적으로 저하되고 디스크에 어떤 시크릿도 쓰이지 않아요.

OAuth 인증

OAuth 2.0이 필요한 HTTP MCP 서버의 경우 서버 구성에 oauth 블록을 추가해요.

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "client_id": "pre-registered-client-id",
        "client_name": "Cortex Code",
        "redirect_port": 8585,
        "scope": "openid mcp read write",
        "authorization_server_url": "https://auth.example.com"
      }
    }
  }
}

첫 연결 시 CoCo는 인증을 위해 내 시스템 브라우저를 열어요. 결과로 얻은 access·refresh 토큰은 OS 키체인에 저장되고 만료 전에 자동으로 새로고침돼요.

필드	설명
`client_id`	인증 서버에 등록된 OAuth 클라이언트 ID. 생략하면 CoCo가 Dynamic Client Registration을 시도해요.
`client_name`	동적 등록 중 표시되는 사람이 읽을 수 있는 클라이언트 이름.
`redirect_port`	OAuth 리다이렉트 URI에 사용되는 로컬 포트. 기본 8585.
`scope`	요청할 OAuth 스코프의 공백 구분 목록.
`authorization_server_url`	인증 서버의 URL. 생략하면 CoCo가 MCP 서버의 메타데이터에서 발견해요.

참고

서버의 OAuth 자격 증명을 재설정하려면 cortex mcp remove <server>를 실행하고 서버를 다시 추가해요. 그런 다음 cortex mcp start를 실행해 모든 구성 서버에 재연결하고 새 OAuth 흐름을 트리거할 수 있어요.

서버 비활성화

구성에서 제거하지 않고 MCP 서버를 일시적으로 비활성화할 수 있어요. /mcp 뷰어에서 서버를 선택하고 끄세요. 비활성화 상태는 다음에 저장돼요.

~/.snowflake/cortex/mcp-disabled.json

비활성화된 서버는 세션 시작 시 연결되지 않고, 그 도구는 에이전트에 노출되지 않으며, 자동 재연결되지 않아요. 언제든 /mcp에서 다시 켤 수 있어요.

MCP 도구 사용

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

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

도구 결과는 50KB로 제한돼요. 도구가 더 많은 데이터를 반환하면 출력이 잘리고 CoCo가 잘린 지점에 안내를 추가해요.

샘플 구성

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 통합(env가 있는 stdio)

{
  "mcpServers": {
    "sourcegraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourcegraph/mcp-server"],
      "env": {
        "SRC_ACCESS_TOKEN": "${SOURCEGRAPH_TOKEN}",
        "SRC_ENDPOINT": "https://sourcegraph.company.com"
      }
    }
  }
}

플러그인 선언 MCP 서버

플러그인은 plugin.json에 선언해 배포와 함께 MCP 서버를 담을 수 있어요. 플러그인이 활성일 때 이 서버들은 자동으로 로드돼요.

{
  "name": "my-plugin",
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"]
    }
  }
}

플러그인 MCP 서버는 사용자·프로필 서버보다 우선순위가 낮아요 — 플러그인은 내가 직접 구성한 서버를 덮어쓸 수 없어요. 자세한 내용은 CoCo CLI plugins 문서를 참고해요.

관리자 제어

관리자는 managed settings로 MCP 사용을 제한할 수 있어요.

사용자 MCP 서버 비활성화. areUserMcpServersAllowed가 false로 설정되면 CoCo는 ~/.snowflake/cortex/mcp.json을 완전히 무시하고 관리자나 Snowflake 연결 프로필이 제공한 서버만 로드해요. 플러그인 선언 MCP 서버도 이 모드에서 건너뛰어져요.
URL 허용 목록. 관리자는 허용된 MCP 엔드포인트 URL 집합을 제한할 수 있어요. URL이 허용되지 않는 서버는 구성 병합 후 조용히 제거돼요.
강제 서버. 관리자는 항상 적용되는 기본 mcp.json을 제공할 수 있어요. 사용자는 강제 서버를 제거하거나 수정할 수 없어요.

전체 강제 스키마는 managed settings를 참고해요.

MCP 문제 해결

서버가 연결되지 않음

/mcp를 실행하고 서버 상태와 마지막 오류를 확인해요.
터미널에서 cortex mcp start를 실행하고 오류 출력을 확인해요.
MCP 클라이언트·매니저 로그를 위해 ~/.snowflake/cortex/logs/를 확인해요.
필요한 환경 변수가 내 셸에 설정되어 있는지 확인해요(echo $VAR).

도구가 나타나지 않음

cortex mcp list를 실행해 서버가 구성되었는지 확인해요.
도구 이름이 영숫자, 밑줄, 또는 하이픈이고 64자 이하인지 확인해요. 잘못된 도구 이름을 노출하는 MCP 서버는 거부돼요.
서버가 ~/.snowflake/cortex/mcp-disabled.json에서 비활성화되지 않았는지 확인해요.

OAuth 문제

cortex mcp remove <server>로 캐시된 자격 증명을 지우고 서버를 다시 추가해 새 흐름을 트리거해요.
포트 8585(또는 구성된 redirect_port)가 사용 가능한지 확인해요.
내 인증 서버가 Dynamic Client Registration을 지원하면 client_id를 생략하고 CoCo가 대신 등록하게 해요.

환경 변수가 확장되지 않음

모호성을 피하려면 맨 $VAR보다 중괄호가 있는 \${VAR}을 선호해요.
변수가 내 셸에서 export 되어 있는지 확인해요(echo $VAR).
CoCo가 편집기의 임베디드 셸이 아니라 CLI가 실행될 때의 프로세스 환경에서 변수를 확장한다는 점을 기억해요.

출력 잘림

도구 결과는 50KB로 제한돼요. 큰 데이터셋의 경우 MCP 서버가 요약, 참조, 또는 CoCo가 후속 단계에서 읽을 수 있는 파일 포인터를 반환하게 해요.

MCP 모범 사례

설명적인 서버 이름을 사용해요. 서버 이름이 도구 네임스페이스에 나타나므로, 도구 호출이 스스로 설명되게 이름을 골라요(예: mcp__github__search가 mcp__gh1__search보다 명확해요).
자격 증명을 보호해요. 환경 변수나 OAuth를 사용해요. mcp.json에 토큰을 절대 하드코딩하지 마요.
적절한 타임아웃을 설정해요. 기본 도구 타임아웃은 60초예요. 오래 실행되는 도구에는 늘리고, 응답 없는 서버에 빠르게 실패하려면 줄여요.
연결을 먼저 테스트해요. 서버를 추가하거나 업데이트한 뒤 cortex mcp start를 실행해 에이전트 세션에서 의존하기 전에 연결되고 원하는 도구를 노출하는지 확인해요.
권한을 좁게 범위를 정해요. permissions.json의 allow·deny 목록으로 안전한 읽기 전용 도구를 사전 승인하고 파괴적인 도구를 명시적으로 거부해요.

더 알아보기

Model Context Protocol (Desktop) — 데스크톱 MCP
CoCo CLI plugins — 플러그인 MCP 서버
Managed settings — 관리자 강제