mcp

이식 가능한 MCP 연결 정의를 관리하고 네이티브 Agent 설정과 동기화합니다. Set up MCP once부터 시작하세요.

Commands

skillshare mcp
skillshare mcp add
skillshare mcp edit
skillshare mcp edit docs --url https://updated.example/mcp --no-tui
skillshare mcp add docs --url https://example.com/mcp --target claude --sync
skillshare mcp add local --target codex -- company-mcp --workspace /path/to/workspace
skillshare mcp import docs --from claude --target claude --target cursor --sync
skillshare mcp import docs --file ./provider.json --target claude
skillshare mcp list --json
skillshare mcp check
skillshare mcp check docs --json --no-dns
skillshare mcp check --live --timeout 30s
skillshare mcp remove docs --sync
skillshare mcp remove docs --keep-files
skillshare mcp restore BACKUP_ID --dry-run
skillshare mcp serve
skillshare mcp serve --target claude --http 127.0.0.1:8765
skillshare mcp serve --check
skillshare sync mcp --dry-run --json
skillshare sync mcp
skillshare sync --all

Option	Meaning
--target CLIENT	수신 client; 여러 client를 선택하려면 반복 지정. --target none은 서버를 어떤 client에도 쓰지 않고 Skillshare에만 유지합니다. 아래 참고. serve에서는 --target NAME이 대신 skills target을 지정합니다. 아래 참고
--url URL	add용 Streamable HTTP 엔드포인트
-- command args...	add용 로컬 실행 파일과 리터럴 인자
--disabled	project mode에서 add와 함께 사용: Agent의 global 설정이 정의한 서버를 끕니다. 아래 참고
--tools-allow TOOLS	이 도구만 허용, 쉼표로 구분; *는 임의의 문자와 일치; ""는 값을 지웁니다. 도구 정책 참고
--tools-deny TOOLS	이 도구는 항상 제외, 쉼표로 구분; allow보다 우선; ""는 값을 지웁니다. 도구 정책 참고
--pi-options JSON	Pi 내장 MCP의 그 밖의 서버별 필드를 JSON 객체로 지정. Pi 참고
--from CLIENT	import할 기존 client, 또는 --file의 형식
--file PATH	네이티브 JSON/JSONC, TOML 또는 Goose YAML; .toml은 기본적으로 Codex로 처리되며, 다른 형식은 MCP 섹션에서 감지됨; 명시적인 방언을 지정하려면 --from 사용
--sync	저장 후 동기화; noninteractive add/import/remove는 그렇지 않으면 저장만 함
--keep-files	remove와 함께 사용: 서버 관리를 멈추고 Agent 항목은 그대로 둡니다. --sync와 함께 쓸 수 없습니다. 아래 참고
--replace	add/import 중 기존 source 정의를 명시적으로 교체; import 시 가져온 client의 항목이 다르면 이것도 다시 작성
--dry-run, -n	저장하거나 네이티브 구성을 작성하지 않고 미리보기
--json	구조화된 출력; sync/preview 보고서에는 이름, 경로, 작업만 포함되며 서버 값은 포함되지 않음
--no-dns	check와 함께 사용: 원격 서버의 호스트 조회를 건너뜀. 아래 참고
--live	check와 함께 사용: 각 로컬 서버를 시작하고 각 원격 서버를 호출하는 검사도 수행. 아래 참고
--timeout DURATION	check --live와 함께 사용: 서버별 프로브 제한 시간 (예: 30s); 기본값 10s
--http ADDR	serve와 함께 사용: stdio 대신 ADDR에서 Streamable HTTP를 수신. 아래 참고
--tls-cert FILE, --tls-key FILE	serve --http와 함께 사용: 이 PEM 인증서와 키로 HTTPS를 제공; loopback이 아니면 필수
--check	serve와 함께 사용: 건너뛸 skill과 그 이유를 나열하고 서버를 시작하지 않고 종료
--no-tui	대화형 메뉴 비활성화; tui: false, --json, 또는 비터미널 입출력에서도 비활성화됨
--revision ID	add/import/remove 또는 sync mcp에 일치하는 미리보기 요구
--global, -g	global Skillshare 구성 사용
--project, -p	project Skillshare 구성 사용

서브커맨드 없이 실행하면 mcp는 대화형 터미널에서 검색 가능한 관리자를 열거나, noninteractive mode에서는 상태를 출력합니다. 이름 없이 noninteractive import를 실행하면 선택할 수 있도록 파싱된 후보 목록을 표시하며 저장하지 않습니다. 후보는 이식 가능한 정의를 포함하며, 인식 가능한 시크릿은 참조로 변환됩니다. Agent 고유 필드는 경고로 표시되고 제외되며, 비활성화된 서버와 지원되지 않는 전송 방식은 후보를 차단합니다. restore는 적용 전에 항상 다시 미리보기를 표시하며, 적용하지 않고 확인하려면 --dry-run을 사용하세요.

--pi-extension, --pi-options-prune, --direct-tools는 0.23.0에서 제거되었으며, 이제 대신 무엇을 써야 하는지 알려주는 메시지와 함께 실패합니다. 0.22에서 Pi 업그레이드하기를 참고하세요.

sync mcp는 scope flag, --dry-run, --json, --no-tui, --revision을 받습니다. sync --all은 skill, agent, extras, MCP + hooks를 포함하며, 일반 sync는 기존 리소스 동작을 유지합니다. MCP 충돌은 --all이 다른 리소스를 변경하기 전에 확인됩니다. 리소스 유형과 네이티브 파일은 하나의 트랜잭션이 아니라 별개의 작업입니다.

Interactive management

skillshare mcp 또는 skillshare mcp list를 실행하면 연결을 추가, import, 편집, 제거, 동기화, 복원할 수 있으며, 선택한 연결의 상세 정보가 목록 옆에 표시됩니다. 연결 목록은 인자, 헤더, 환경 변수 값을 숨기며 URL 쿼리를 생략합니다. 키는 화면 하단에 표시됩니다.

mcp edit, mcp remove, mcp restore는 이름이나 백업 ID가 생략된 경우 선택 메뉴를 제공합니다. 편집기는 command/URL, 인자, 환경 변수, HTTP 헤더, bearer-token 환경 참조, 수신 target, 도구 정책(Tools)을 다룹니다. 인자는 줄당 하나의 리터럴 인자 또는 JSON 배열로 입력할 수 있습니다. 전송 방식을 전환하면 새 연결 유형에 적용되지 않는 필드는 지워집니다.

Add, edit, remove, import는 Save and sync 또는 Save only 전에 미리보기를 표시합니다. Remove는 --keep-files와 같은 Stop managing도 제공합니다. Escape를 누르면 대기 중인 초안이 취소됩니다. Restore는 Agent 항목에 대한 변경 사항을 미리보고 확인하지만, source 정의는 다시 작성하지 않습니다.

서버 이름 없이 import하면 여러 항목을 선택할 수 있습니다. 유효하지 않은 후보는 건너뛰며, --replace를 지정하지 않는 한 기존 source 이름은 건너뜁니다. 배치 전체에 대해 호환되는 하나의 수신 client 집합을 선택하세요. 전체 배치는 source가 한 번 저장되기 전에 검증되며, 이후의 네이티브 파일 I/O 실패는 기존 복구 동작을 유지합니다.

스크립트에서는 이름과 flag를 제공하세요. mcp edit NAME --url URL, mcp edit NAME --target CLIENT, mcp edit NAME -- command args...는 다른 해당 설정을 유지하면서 지정된 필드만 업데이트합니다. --sync가 추가되지 않는 한 저장만 합니다. --no-tui를 사용하면 remove는 이름이, restore는 백업 ID가 필요합니다. --dry-run은 변경 사항을 저장하거나 동기화하지 않습니다.

Source fields

인라인 mcp.servers 또는 sources.mcp로 지정한 외부 파일 중 하나를 선택하세요. 외부 파일에는 최상위 servers 매핑이 있습니다. mcp.targets와 mcp.projects는 Skillshare 설정에 남아 있습니다. 스키마는 저장소의 schemas/mcp.schema.json입니다.

Server field	Meaning
command	로컬 실행 파일; url과 함께 사용 불가
args	로컬 실행 파일용 리터럴 인자 목록
env	로컬 환경 값: 문자열 또는 {fromEnv: VARIABLE}
url	HTTP(S) MCP 엔드포인트; 자격 증명이나 fragment 포함 불가
headers	HTTP 헤더: 문자열 또는 {fromEnv: VARIABLE}
bearerToken	{fromEnv: VARIABLE}; Authorization 헤더와 공존 불가
transport	선택적으로 stdio 또는 streamable-http; 생략 시 추론됨
targets	선택적 수신 client; mcp.targets를 재정의. 빈 목록이면 서버를 Skillshare에만 유지합니다. 아래 참고
tools	어떤 도구가 모델에 전달되는지: allow, deny. 한 번 작성하면 Agent별로 변환됩니다. 도구 정책 참고
piOptions	Pi 내장 MCP의 그 밖의 서버별 필드. Pi 참고
disabled	true만 가능, 다른 연결 필드 불가, 그리고 project가 scope 안에 있어야 합니다: project mode이거나 mcp.projects 아래의 root. 아래 참고

Client ID는 claude, codex, cursor, vscode, opencode, kilocode, grok, antigravity, amp, claude-desktop, cline, copilot, factory, gemini, goose, junie, kiro, lmstudio, warp, windsurf, pi, omp입니다. grok은 공식 xAI Grok CLI를 의미합니다. 서버 이름은 문자, 숫자, 점, 밑줄, 하이픈을 사용합니다. 서버는 동기화 전에 직접 또는 mcp.targets를 통해 최소 하나의 client를 선택해야 합니다. 단, 서버 자체의 targets가 빈 목록인 경우는 예외입니다.

Keep a server without syncing it

targets: []인 서버는 Skillshare source에 남아 있으며 어떤 client에도 작성되지 않습니다. 정의는 나중을 위해 유지하면서 서버를 모든 client에서 빼고 싶을 때 사용하세요. 이전에 동기화된 적이 있다면, 다음 sync에서 해당 client의 항목이 제거됩니다.

mcp:
  targets: [claude, codex]
  servers:
    docs:
      url: https://example.com/mcp
      targets: []

skillshare mcp add docs --url https://example.com/mcp --target none
skillshare mcp edit docs --target none
skillshare mcp edit docs --target claude   # 다시 되돌리기

• targets를 생략하는 것은 다릅니다. 그 경우 서버는 mcp.targets를 상속하며, 해당 목록도 비어 있으면 거부됩니다.
• none은 client와 함께 지정할 수 없습니다.
• 터미널 선택 메뉴에서는 client를 선택하지 않은 채로 확인하세요. 대시보드에서는 모든 client의 체크를 해제하세요. 서버에 아직 Agent 없음 태그가 붙습니다.
• project의 서버와 mcp.projects 아래의 서버에도 동일하게 동작합니다.
• disabled 항목은 어딘가에서 서버를 꺼야 하므로 여전히 최소 하나의 client가 필요합니다.
• mcp list는 이러한 서버를 kept no targets로 표시합니다.

Grok의 경우, 이름은 문자나 밑줄로 시작해야 하고, 문자·숫자·하이픈·단일 밑줄만 포함할 수 있으며, 밑줄로 끝날 수 없습니다. company-docs와 같은 이름은 지원되는 모든 client에서 동작합니다.

Native destinations

Client	Global	Project	Section
Claude Code	~/.claude.json	.mcp.json	mcpServers
Codex	~/.codex/config.toml	.codex/config.toml	mcp_servers
Cursor	~/.cursor/mcp.json	.cursor/mcp.json	mcpServers
VS Code	User mcp.json (below)	.vscode/mcp.json	servers
OpenCode	~/.config/opencode/opencode.json	opencode.json	mcp
Kilo Code	~/.config/kilo/kilo.jsonc	kilo.jsonc	mcp
Grok CLI	~/.grok/config.toml	.grok/config.toml	mcp_servers
Antigravity (AGY)	~/.gemini/config/mcp_config.json	.agents/mcp_config.json	mcpServers
Amp	~/.config/amp/settings.json	.amp/settings.json	amp.mcpServers (literal key)
Claude Desktop	Claude application data directory, claude_desktop_config.json	Global only	mcpServers
Cline	~/.cline/data/settings/cline_mcp_settings.json	Global only	mcpServers
Copilot CLI	~/.copilot/mcp-config.json	.github/mcp.json	mcpServers
Factory Droid	~/.factory/mcp.json	.factory/mcp.json	mcpServers
Gemini CLI	~/.gemini/settings.json	.gemini/settings.json	mcpServers
Goose	~/.config/goose/config.yaml	Global only	extensions (YAML)
Junie	~/.junie/mcp/mcp.json	.junie/mcp/mcp.json	mcpServers
Kiro	~/.kiro/settings/mcp.json	.kiro/settings/mcp.json	mcpServers
LM Studio	~/.lmstudio/mcp.json	Global only	mcpServers
Warp	~/.warp/.mcp.json	.warp/.mcp.json	mcpServers
Windsurf (Cascade)	~/.codeium/windsurf/mcp_config.json	Global only	mcpServers
Oh My Pi (OMP)	~/.omp/agent/mcp.json	.omp/mcp.json	mcpServers

대시보드의 서버 폼은 fromEnv 참조를 포함해 HTTP 헤더를 환경 변수와 동일한 방식으로 편집합니다. 서버 메뉴와 폼의 파일 개수 옆에 있는 View what each Agent gets는, 선택한 client에 대해 Sync가 작성할 네이티브 텍스트를 읽기 전용으로 보여줍니다. 폼에서는 아직 저장되지 않은 편집 내용이 반영됩니다. 시크릿은 참조 형태로 유지됩니다.

JSON 항목은 파일 자체의 들여쓰기에 맞춰 필드마다 한 줄씩 작성됩니다. Skillshare가 소유하지만 여전히 한 줄에 있는 항목은 update로 보고되며 다시 레이아웃되어 작성됩니다. 소유하지 않는 항목과 사람이 직접 서식을 지정한 항목은 레이아웃이 유지됩니다.

대시보드는 현재 scope와 호스트 플랫폼에서 사용 가능한 대상만 제공합니다. 각 서버는 한 행이며, 이름 아래에 전달될 client가 chip으로 표시됩니다. 오른쪽의 카운트 버튼은 해당 서버의 전체 client 목록을 엽니다. Global 전용 client는 project mode에서 선택할 수 없습니다. 오른쪽의 Sync 박스는 아직 작성되지 않은 변경 사항을 나열합니다: client를 체크하면 source만 편집됩니다. Sync MCP는 그 변경 사항을 나열하고, 확인하면 MCP 설정 파일만 작성하며 각 파일의 백업을 남깁니다. 같은 박스의 구분선 아래에서는 서버가 있으면 검사로 서버를 검사하고, 백업 및 복원로 그 백업을 살펴볼 수 있습니다. 그 아래의 Agents는 이 머신에서 감지된 client를 나열합니다. client의 MCP 파일이 존재하거나, 해당 client가 설정을 보관하는 폴더가 존재하면 감지된 것으로 간주하므로, MCP 파일이 아직 없는 새 설치도 표시됩니다. project mode에서는 프로젝트에 MCP 파일이 있거나 client가 전역적으로 감지된 경우 나열됩니다.

추가 client 세부 정보:

• codex 대상은 Codex CLI, Codex IDE 확장, ChatGPT 데스크톱 앱이 공유하는 하나의 config.toml이므로, codex로 동기화된 서버는 셋 모두에 나타납니다. ChatGPT 데스크톱 앱은 Settings → MCP servers에 이를 나열합니다. Codex는 신뢰하는 프로젝트에서만 .codex/config.toml을 읽습니다. 신뢰하지 않는 프로젝트에서는 동기화된 서버가 오류 없이 로드되지 않습니다. cwd, http_headers_helper, 승인 모드, 타임아웃, oauth 테이블은 이식 가능한 형태가 없습니다: import는 이를 경고와 함께 제외하고, sync는 기존 항목에 그대로 유지합니다. enabled_tools와 disabled_tools는 도구 정책에서 만들어지며, import 시 도구 정책으로 가져옵니다. Codex 플러그인이 번들하는 MCP 서버는 plugins.<plugin>.mcp_servers 아래에 구성되며 여기서 관리되지 않습니다.
• Claude Desktop 파일 동기화는 macOS와 Windows에서 stdio만 지원합니다. 디렉터리는 macOS에서 ~/Library/Application Support/Claude, Windows에서 %APPDATA%/Claude입니다. 원격 커넥터는 애플리케이션에서 구성하세요.
• Cline은 기본 VS Code Stable 프로필을 대상으로 하며, Cline CLI나 다른 IDE는 대상이 아닙니다.
• Copilot CLI 항목에는 tools가 작성됩니다: 도구 정책이 허용하는 정확한 도구 이름이며, 그렇지 않으면 ["*"]입니다. import는 tools를 다시 도구 정책으로 읽어옵니다. 프로젝트 .mcp.json이 존재하면, Copilot이 .github/mcp.json보다 그 파일을 먼저 읽기 때문에 sync가 중단됩니다. 먼저 파일을 통합하세요. project mode에서 Claude Code와 Copilot CLI를 함께 선택하는 것도 파일을 작성하기 전에 차단됩니다. 이 중 하나의 client에는 global mode를 사용하세요.
• Gemini는 Streamable HTTP에 httpUrl을 사용합니다. url 필드는 레거시 SSE를 의미하며 import 시 거부됩니다. Cline은 type: streamableHttp를, Goose는 type: streamable_http와 uri를 사용합니다. Skillshare가 이를 자동으로 변환합니다.
• Windows용 Goose는 %APPDATA%/Block/goose/config/config.yaml을 사용합니다. YAML 편집은 관련 없는 설정, 주석, 내장 확장을 유지하지만 서식이 바뀔 수 있습니다. Alias, merge, 중복 키, 다중 문서는 편집을 차단합니다. 내장 확장과 keychain env_keys는 이식 가능한 MCP 연결로 import할 수 없습니다.
• Claude Code는 내장 서버용으로 예약된 이름인 workspace, claude-in-chrome, computer-use라는 이름의 서버를 건너뜁니다. 또한 자체 자격 증명을 원격 서버로 전송하지 않습니다: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY, NPM_TOKEN은 url과 headers에서 빈 값으로 읽힙니다. Skillshare는 Claude에 대해 둘 다 거부합니다. 자격 증명은 자체적으로 이름을 지은 변수에 복사하세요.
• Claude Code는 로컬 scope도 가지고 있습니다: --scope 없이 claude mcp add로 추가된 서버는 프로젝트별로 ~/.claude.json에 저장됩니다. 로컬 서버는 .mcp.json 이나 user scope에 있는 동일한 이름의 서버보다 항상 우선합니다. project mode에서 Skillshare는 이러한 서버를 그것이 가리는 항목 옆에 표시하며, sync를 막지는 않습니다. 프로젝트 폴더에서 claude mcp remove NAME -s local로 제거하세요.
• Cline의 VS Code 확장, CLI, SDK는 ~/.cline/data/settings/를 공유합니다. 확장은 이전 VS Code globalStorage 파일을 한 번 그곳으로 옮긴 후 더 이상 읽지 않으므로, Skillshare는 ~/.cline/data가 아직 존재하지 않을 때만 이전 파일에 씁니다. CLINE_MCP_SETTINGS_PATH, CLINE_DATA_DIR, CLINE_DIR은 이 순서로 존중됩니다.
• Windsurf 지원은 문서화된 Cascade 구성을 대상으로 합니다. Windsurf의 최신 Devin Local agent는 자체 ~/.config/devin/mcp_config.json을 읽으며, Skillshare는 이를 관리하지 않습니다. Warp 프로젝트 연결은 세션마다 Warp 내부에서 승인이 필요합니다.
• Amp는 amp mcp approve <name> 이후에만 프로젝트의 .amp/settings.json에서 서버를 실행합니다. Global 서버는 승인이 필요 없습니다.
• Kiro는 "Mcp Approved Env Vars" 설정에 나열된 이름에 대해서만 ${VARIABLE}을 확장하며, localhost에 한해 http:// URL을 허용합니다.
• VS Code는 User/profiles/ 아래의 기본이 아닌 각 프로필마다 별도의 mcp.json을 유지합니다. Skillshare는 기본 프로필의 파일을 관리합니다.

환경 참조는 Amp, Copilot CLI, Factory, Gemini CLI, Kiro에 대해 ${VARIABLE}로, Cline과 Windsurf에 대해 ${env:VARIABLE}로 내보내집니다. Claude Desktop, Goose, Junie, LM Studio, Warp는 네이티브 보간이 검증되지 않았기 때문에 현재 fromEnv와 bearerToken export를 거부합니다. 사용자 정의 자격 증명이 없는 연결을 사용하거나, 지원되는 경우 수신 client에서 인증하세요. Skillshare는 참조를 평문으로 해석하지 않습니다.

Antigravity는 원격 연결용 serverUrl을 포함한 현재 공식 MCP 구성을 사용합니다. Skillshare는 이식 가능한 url을 자동으로 변환합니다. 이전 .gemini/antigravity/와 .gemini/antigravity-cli/ 구성 위치는 관리되지 않습니다. Antigravity의 fromEnv와 bearerToken export는 문서화된 구성에 환경 보간이 명시되어 있지 않기 때문에 차단됩니다. 사용자 정의 시크릿 헤더가 필요 없는 연결을 사용하고, 지원되는 OAuth 로그인을 Antigravity 내부에서 완료하세요. Skillshare는 참조를 평문 자격 증명으로 확장하지 않습니다.

OpenCode는 global 디렉터리에 대해 XDG_CONFIG_HOME을 존중합니다. 기존 opencode.jsonc는 opencode.json을 생성하는 대신 사용됩니다. 프로젝트에서는 OpenCode가 .opencode/에서도 두 이름을 모두 읽으므로, 그곳에 둔 파일이 있으면 Skillshare는 그 파일에 쓰며, 새 파일은 프로젝트 루트에 생성됩니다. 둘 이상 존재하면 동기화 전에 통합하세요. 사용자 지정 OpenCode 구성 경로, 디렉터리 오버라이드, 인라인 구성, 상속된 상위 파일은 관리되지 않습니다. 이들은 OpenCode에서 선택한 대상을 재정의할 수 있습니다.

Kilo Code는 OpenCode와 동일한 형식을 사용합니다. 프로젝트 루트와 .kilo/에서 kilo.jsonc와 kilo.json을 읽고 병합하므로, Skillshare는 이미 존재하는 파일에 쓰며 아무것도 없을 때만 kilo.jsonc를 생성합니다. 둘 이상 존재하면 동기화 전에 통합하세요. KILO_CONFIG, KILO_CONFIG_DIR, 이전 VS Code 확장의 mcp_settings.json은 관리되지 않습니다.

Kilo Code는 프로젝트 구성을 신뢰할 수 없는 것으로 취급합니다. 그곳에서는 {env:VARIABLE} 참조를 허용하지 않으며, 그런 참조를 발견하면 프로젝트 파일 전체를 무시합니다. 따라서 project mode에서 Skillshare는 fromEnv나 bearerToken을 사용하는 Kilo Code 서버를 거부합니다. 참조가 허용되는 global mode에서 해당 서버를 정의하세요.

OpenCode와 Kilo Code는 local/remote 유형과 {env:VARIABLE} 참조를 사용하며, Grok은 ${VARIABLE} 참조를 사용합니다. Skillshare가 이를 자동으로 변환합니다. Claude의 "type": "streamable-http"는 HTTP로 import됩니다. 비활성화된 연결은 import를 차단합니다. Codex의 startup_timeout_sec나 envFile처럼 이식 가능한 대응 항목이 없는 다른 네이티브 옵션은 경고와 함께 import에서 제외되며, sync는 Agent의 기존 항목에 이를 유지합니다. Pi는 내장 MCP를 사용합니다. 아래를 참고하세요.

VS Code Stable의 기본 사용자 파일은 다음과 같습니다.

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ${XDG_CONFIG_HOME:-~/.config}/Code/User/mcp.json
• Windows: %APPDATA%/Code/User/mcp.json

Global Claude, Codex, Grok, Copilot 경로는 CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME, COPILOT_HOME을 존중합니다. OPENCODE_CONFIG와 OPENCODE_CONFIG_DIR은 관리되지 않습니다. Amp와 Goose는 .config 경로를 사용하는 플랫폼에서 XDG_CONFIG_HOME을 존중합니다. Project 대상은 선택한 프로젝트 루트를 기준으로 합니다. 프로젝트 신뢰, 서버 승인, 인증은 여전히 수신 Agent의 책임입니다.

Another account of an Agent

Agent의 다른 계정으로 선언된 target은 claude(CLAUDE_CONFIG_DIR), codex(CODEX_HOME), pi와 omp(둘 다 PI_CODING_AGENT_DIR 사용)에 대해 MCP target이기도 합니다. 그 서버는 해당 Agent의 형식으로, 계정 자체의 파일에 작성됩니다. Claude는 <config_dir>/.claude.json, Codex는 <config_dir>/config.toml, Pi와 OMP는 <config_dir>/mcp.json입니다.

targets:
  claude-work:
    agent: claude
    config_dir: ~/.claude-work

mcp:
  targets: [claude, claude-work]      # 두 계정 모두 모든 서버를 받음
  servers:
    docs:
      url: https://example.com/mcp
    jira:
      command: jira-mcp
      targets: [claude-work]          # 업무용 계정만

여기서 docs는 ~/.claude.json과 ~/.claude-work/.claude.json에 작성되고, jira는 두 번째 파일에만 작성됩니다. --target claude-work는 mcp add와 mcp edit에서 동작하며, 대시보드는 이 계정을 Agent 옆에 나열합니다.

모든 계정은 동일한 프로젝트 파일을 읽으므로, mcp.projects 안과 project mode에서는 Agent 자체의 이름을 사용하세요. Claude Code는 프로젝트의 off 목록을 각 계정의 파일에 유지합니다. 프로젝트에서 서버를 끄면 해당 서버를 가진 모든 계정에 스위치가 작성됩니다. mcp import --from claude-work와 대시보드의 Import from target은 계정 자체의 파일을 읽습니다. mcp import --file <path> --from claude-work는 직접 내보낸 파일을 해당 계정의 Agent 형식으로 읽습니다.

Turn off a global server in one project

Agent는 자체 global MCP 파일과 프로젝트 파일을 함께 읽습니다. 따라서 global 파일에 정의된 서버는 모든 프로젝트에서 로드됩니다. 특정 프로젝트에서 로드되지 않도록 막으려면, Agent의 global 파일이 사용하는 것과 동일한 이름으로 항목을 추가하고 disabled로 표시하세요.

이는 다음 다섯 client에서만 동작합니다.

Client	Supported	What Skillshare writes
Claude Code	예	~/.claude.json: 이름을 이 프로젝트의 disabledMcpServers 목록에 추가
OpenCode	예	opencode.json: "NAME": {"enabled": false}
Kilo Code	예	kilo.jsonc: "NAME": {"enabled": false}
Pi	예, Pi 1.0.1부터	.pi/mcp.json: "NAME": {"enabled": false}, 아래 참조
Oh My Pi	예	.omp/mcp.json: "NAME": {"enabled": false}가 같은 이름의 사용자 항목을 가림
Codex	아니요	아래 참고
Every other client	아니요	하나를 선택하면 오류가 발생하며 아무것도 작성되지 않음

스위치만 작성됩니다. OpenCode, Kilo Code, Pi는 global 항목의 command나 URL을 그대로 유지합니다. OMP는 이름 중복 제거 전에 비활성화된 project 항목을 억제하므로 같은 이름의 사용자 항목이 연결되지 않습니다. 다른 client는 전체 global 항목을 프로젝트 항목으로 대체하거나 프로젝트 파일이 없기 때문에 거부됩니다. 그런 경우 단독 스위치만으로는 서버를 끄는 대신 오히려 서버를 망가뜨리게 됩니다.

Codex는 다른 이유로 거부됩니다. Codex는 .codex/config.toml을 필드 단위로 global 파일 위에 병합하므로, global 구성이 해당 서버를 정의하는 머신에서는 enabled = false만으로도 동작합니다. 정의하지 않는 머신에서는 병합된 항목에 command나 url이 없어 Codex는 invalid transport로 전체 구성을 로드하지 못합니다. .codex/config.toml은 보통 커밋되므로, 한 팀원의 스위치가 다른 팀원의 Codex 시작을 막을 수 있습니다. 대신 ~/.codex/config.toml에서 enabled = false로 머신별로 서버를 끄세요.

Pi는 같은 이름의 프로젝트 항목으로 global 항목을 통째로 대체하지만, Pi 1.0.1부터 command, url, type이 없는 항목은 덮어쓰기가 됩니다. global 서버의 enabled, exposure, toolExposure만 바꾸고, args, env, 자격 증명은 global 서버의 것을 그대로 씁니다. Pi의 /mcp가 쓰는 항목도 같습니다. Pi 1.0.1 이전에는 이 항목을 잘못된 항목으로 보고합니다. global Pi 구성에 그 서버가 없는 머신에서는 Pi가 시작할 때 덮어쓸 서버가 없다고 보고하고 나머지는 불러옵니다. 이 스위치는 global 서버에서 아무것도 필요로 하지 않으므로 프로젝트 모드에서도 동작합니다. 이전 릴리스가 global 서버의 command나 url과 함께 쓴 항목은 다음 sync에서 덮어쓰기 항목으로 다시 작성됩니다.

OpenCode and Kilo Code

cd my-project
skillshare mcp add company-docs --disabled --target opencode --target kilocode
skillshare sync mcp

# .skillshare/config.yaml
mcp:
  servers:
    company-docs:
      disabled: true
      targets: [opencode, kilocode]

Claude Code

Claude Code는 한 scope에서 전체 서버 항목을 가져오며 필드를 병합하지 않으므로, .mcp.json의 스위치는 서버를 끄는 대신 대체해 버립니다. Claude Code는 /mcp 패널이 편집하는, ~/.claude.json에 있는 자체 프로젝트별 off 목록을 유지합니다. Skillshare는 이 프로젝트의 절대 경로 아래에 이름을 추가하며, .mcp.json에는 아무것도 쓰지 않습니다.

skillshare mcp add company-docs --disabled --target claude
skillshare sync mcp

• 이 목록은 저장소가 아니라 여러분의 머신에 있습니다. 각 팀원은 자신의 체크아웃에서 skillshare sync mcp를 한 번 실행합니다.
• /mcp에서 직접 끈 이름은 절대 가져오거나 제거되지 않습니다.
• /mcp에서 서버를 다시 켜면, 다음 sync에서 충돌이 보고됩니다. .skillshare/config.yaml에서 항목을 제거하거나, replace하여 다시 끄세요.
• 목록은 프로젝트의 경로로 키가 지정되므로, 프로젝트를 이동하면 새 sync가 필요합니다.

Rules

• project가 scope 안에 있어야 합니다. skillshare init -p로 생성된 .skillshare/config.yaml이 있는 프로젝트 안에서 실행하거나, -p를 전달하거나, 항목을 mcp.projects의 프로젝트 root 아래에 두세요. project가 scope에 없는 global mcp.servers에서는 거부됩니다.
• disabled는 단독으로 사용됩니다. 항목은 targets만 받습니다. command, url, env, headers, piOptions, tools를 추가하면 오류입니다.
• targets는 생략할 수 있습니다. 그러면 항목은 프로젝트의 target을 따릅니다: sync할 때마다 프로젝트가 사용하는 client 중 프로젝트별 스위치가 있는 client에 작성됩니다. Skillshare가 같은 이름의 global 서버도 알고 있는 mcp.projects 아래에서는 그 서버가 작성되는 client로 더 좁혀집니다. 나중에 프로젝트의 target을 변경해도 항목을 수정할 필요가 없습니다. 직접 정하려면 targets를 명시하세요. 그 목록에 지원되지 않는 client가 있으면 오류입니다.
• 이름이 일치해야 합니다. Skillshare는 Agent의 global 파일을 읽지 않으므로, 이 이름의 서버가 그곳에 존재하는지 확인할 수 없습니다. 아무것도 일치하지 않는 이름은 문제가 되지 않습니다: Agent가 이를 무시할 뿐입니다.
• 다시 켜려면, 항목을 제거하고(skillshare mcp remove company-docs) sync하세요. 스위치가 작성된 파일에서 제거됩니다: 프로젝트 자체 파일, 또는 Claude Code의 경우 ~/.claude.json.
• Skillshare가 직접 정의하는 서버는 이것이 필요 없습니다. 대신 해당 서버에서 Agent 선택을 해제하면, 다음 sync에서 그 항목이 제거됩니다.

대시보드에서는 전역 서버 끄기 버튼이 이에 해당합니다. project mode에서는 서버 제목 옆에, 프로젝트의 MCP 탭에서는 서버 추가 옆에 있습니다.

Manage several projects from the global config

Project mode는 각 프로젝트의 MCP 설정을 해당 프로젝트의 .skillshare/config.yaml에 보관하며, 그 폴더 안에서 sync합니다. 모든 프로젝트를 한곳에서 관리하고 싶다면, global 설정의 mcp.projects 아래에 프로젝트 폴더를 나열하세요. 그러면 어디서든 skillshare sync mcp를 한 번 실행하는 것만으로 global 파일과 모든 프로젝트의 파일이 하나의 plan으로 작성됩니다.

# ~/.config/skillshare/config.yaml
mcp:
  servers:
    context7:
      command: npx
      args: ["-y", "@upstash/context7-mcp"]
      targets: [claude, opencode]
  projects:
    ~/work/project01:
      targets: [claude, opencode]
      servers:
        context7:                  # 이 프로젝트에서만 꺼짐
          disabled: true
    ~/work/project02:
      servers:
        internal-docs:             # 이 프로젝트에만 존재
          url: https://example.com/mcp
          targets: [opencode]

프로젝트에는 global 설정과 다른 부분만 나열합니다. context7 같은 global 서버는 여기에 항목이 필요 없습니다. Agent는 자체 global 파일과 프로젝트 파일을 함께 읽으므로, 이미 모든 프로젝트에서 로드됩니다. disabled 항목은 그곳에 나열된 client에 대해 그 폴더에서 서버를 끕니다.

각 키는 프로젝트 폴더입니다: 절대 경로이거나 ~로 시작하는 경로입니다. 그 아래에는 해당 프로젝트의 자체 config.yaml이 mcp 아래에 담았을 것과 동일한 targets와 servers가 들어가며, 동일한 프로젝트 파일에 작성됩니다. targets가 없는 프로젝트는 global mcp.targets를 상속합니다.

하나의 서버가 둘 이상의 위치에 나타나면 미리보기에 파일 이름이 표시됩니다:

context7     add          opencode (~/.config/opencode/opencode.json)
context7     add          opencode (~/work/project01/opencode.json)

목록에서 프로젝트를 제거하면, 서버를 제거할 때와 마찬가지로 Skillshare가 그곳에 작성한 항목이 다음 sync에서 제거됩니다.

여러 프로젝트에 같은 서버를 제공하려면, YAML anchor로 한 번 정의하고 재사용하세요:

mcp:
  projects:
    ~/work/project01:
      servers:
        internal-docs: &internal-docs
          url: https://example.com/mcp
          targets: [opencode]
    ~/work/project02:
      servers:
        internal-docs: *internal-docs

anchor는 mcp.projects 안에 두세요. mcp.servers에 있는 anchor를 가리키는 alias도 동작하지만, skillshare mcp add와 대시보드는 mcp.servers를 다시 씁니다. 저장할 때 파일이 유효하게 유지되도록 그런 alias를 전체 내용으로 풀어서 작성하므로, 이후 global 서버를 수정해도 더 이상 따라가지 않습니다.

Projects in the dashboard

Global mode에서는 대시보드에 프로젝트 페이지가 있습니다. 이 페이지는 projects와 mcp.projects 아래의 모든 폴더를 나열하며, 각 프로젝트에는 MCP 탭이 있습니다.

• 프로젝트 추가는 폴더와 그 target을 받습니다. MCP를 체크하면 해당 폴더가 mcp.projects 아래에도 나열됩니다.
• MCP 탭은 모든 global 서버를 스위치와 함께 나열합니다. 하나를 끄면 targets 없이 disabled 항목이 저장되므로, 위에서 설명한 대로 프로젝트의 target을 따릅니다. 다시 켜면 그 항목이 제거됩니다. 그 아래에는 해당 프로젝트에만 존재하는 서버가 있습니다.
• 꺼져 있는 서버는 꺼져 있는 Agent의 로고를 표시합니다. 프로젝트의 Agent 중 하나에 프로젝트별 스위치가 없으면, 해당 행은 그 Agent에서는 서버가 여전히 로드된다고 알려줍니다. 프로젝트의 target과 다른 자체 targets를 나열한 항목에는 프로젝트에 맞추기가 표시되며, 이는 targets 없이 항목을 다시 저장합니다.
• 탭의 Sync 박스에 있는 Sync MCP는 전체 MCP 계획을 작성하며, 그 변경 사항 중 몇 개가 이 프로젝트 밖에 있는지 알려줍니다. 프로젝트 페이지 상단의 Sync project는 이 프로젝트의 skill, agent, MCP만 작성합니다.
• MCP 페이지 하단의 기본값은 mcp.targets를 편집합니다.
• 프로젝트 자체의 Agent 파일에 Skillshare가 관리하지 않는 서버가 있으면, 탭은 목록 위에 Import와 함께 이를 알려줍니다. 아래 참고.

저장하면 변경한 프로젝트만 다시 씁니다. 다른 프로젝트는 anchor와 alias를 포함해 YAML이 작성된 그대로 유지되며, ~/work/app으로 작성된 폴더는 ~를 그대로 유지합니다. 이 페이지의 다른 곳과 마찬가지로 저장은 config.yaml만 변경하며, 파일은 Sync가 작성합니다.

제한 사항:

• mcp.projects는 global 설정에서만 읽습니다. 이를 포함한 프로젝트 설정은 거부됩니다.
• 이를 편집하는 명령은 없습니다. skillshare mcp add는 mcp.servers를 관리하며 mcp.projects는 작성된 그대로 둡니다. config.yaml에서 직접 편집하거나 대시보드에서 편집하세요.
• Claude Code에 대한 disabled 항목은 global 서버가 작성되는 것과 같은 파일인 ~/.claude.json에 작성됩니다. Claude Code가 프로젝트별 off 목록을 그곳에 보관하기 때문입니다. 서버 자체는 그대로 둡니다.
• 폴더에 같은 항목을 관리하는 자체 .skillshare/config.yaml도 있으면, plan은 이를 덮어쓰지 않고 충돌로 보고합니다.

Agent가 시작하기 전에 서버 검사하기

skillshare mcp check
skillshare mcp check docs github --json
skillshare mcp check --no-dns

mcp check는 source의 모든 서버 또는 지정한 서버에 대해 "sync된 그대로 동작할까?"에 답합니다. global 설정에서는 mcp.projects 아래 각 root의 서버도 검사하며, 각 Agent의 규칙과 sync 상태는 해당 root 기준으로 읽습니다. 읽기 전용이므로 --live를 추가하지 않는 한 서버를 시작하거나, HTTP 요청을 보내거나, 명령을 실행하거나, 파일을 쓰지 않습니다.

검사	수준
env, headers, bearerToken의 fromEnv 변수가 설정되지 않았거나 비어 있음	error
로컬 서버의 command를 PATH에서 찾을 수 없음 (앞의 ~/는 확장됨)	error
원격 서버의 호스트가 DNS로 조회되지 않음 (제한 3초, --no-dns로 건너뜀)	warning
Agent의 규칙이 서버를 거부함 (예: Claude Code가 예약한 이름)	error
Agent의 항목이 source와 충돌함 (sync mcp --dry-run과 동일)	error
Agent의 항목이 아직 작성되지 않았거나 업데이트되지 않음	warning
서버가 targets: []를 가지며 Skillshare에만 보관됨	info
선택한 Agent가 서버의 도구 정책 일부를 담을 수 없음	warning

변수 값은 출력되지 않습니다. error가 하나라도 있으면 1로, 그렇지 않으면 0으로 종료하며, warning으로는 실패하지 않습니다. 알 수 없는 서버 이름은 error이며 알려진 이름 목록을 보여줍니다. 이름은 global과 각 프로젝트에서 그 이름을 가진 모든 서버를 선택하며, 알려진 이름에는 프로젝트 서버도 포함됩니다.

터미널에서는 프로젝트 서버의 제목에 해당 프로젝트가 표시됩니다:

✓ docs
  · claude: in sync
✗ docs  (project ~/work/app)
  ✗ command no-such-mcp-binary was not found on PATH
  ! claude: not synced yet; run skillshare sync mcp

--json을 사용하면 보고서는 다음 형태입니다:

{
  "servers": [
    {
      "name": "docs",
      "ok": false,
      "findings": [
        { "level": "error", "check": "env", "target": "", "message": "bearerToken reads DOCS_TOKEN, which is not set", "subject": "DOCS_TOKEN" },
        { "level": "warning", "check": "sync", "target": "claude", "message": "not synced yet; run skillshare sync mcp" }
      ]
    },
    {
      "name": "docs",
      "project": "/home/me/work/app",
      "ok": true,
      "findings": [
        { "level": "info", "check": "sync", "target": "claude", "message": "in sync" }
      ]
    }
  ],
  "summary": { "errors": 1, "warnings": 1 }
}

check는 env, command, url, dns, client-rule, sync, targets, tools, live 중 하나입니다. target은 Agent 또는 계정을 나타내며, 결과가 서버 자체에 관한 것이면 비어 있습니다. subject는 env, command, dns 결과에서 변수, 명령, 호스트를 나타내고, 성공한 live 프로브에서는 서버가 보고한 이름을, live 로그인 warning에서는 resource metadata URL을 나타내며, 그 외에는 생략됩니다. project는 서버의 mcp.projects root를 절대 경로로 나타내며 (앞의 ~는 확장됨), global 서버에서는 생략됩니다. summary는 프로젝트 서버를 포함해 보고서의 모든 서버를 집계합니다.

대시보드에서는 MCP 페이지 Sync 박스의 검사 버튼이 같은 검사를 실행합니다. 검사할 서버가 있을 때 나타나고, 클릭할 때만 실행되며, 서버 목록 위에 요약을, 각 서버 아래에 해당 error나 warning을 표시하고, 페이지를 새로 고치면 아무것도 남기지 않습니다. MCP 페이지는 global 서버만 나열하므로, 요약과 각 행에는 global 서버와 이름이 같은 것이라도 프로젝트 서버가 포함되지 않습니다. 프로젝트의 MCP 탭에는 Sync 박스에 자체 검사가 있어 해당 프로젝트 자체 서버를 보고합니다. 변수는 skillshare ui를 시작한 터미널에서 읽습니다.

서버를 실제로 프로브하기

skillshare mcp check --live
skillshare mcp check docs --live --timeout 30s --json

--live는 먼저 정적 검사를 실행한 뒤, 선택한 서버 중 error가 없는 각 서버에 접속합니다. error가 있는 서버나 비활성화된 항목에는 접속하지 않으며, info 결과가 그 이유를 알려줍니다.

• 로컬 (stdio) 서버. Skillshare는 현재 환경에 서버의 env를 더하고, 각 fromEnv 값은 셸에서 읽어 command를 args와 함께 시작합니다. 프로젝트 서버는 해당 프로젝트 폴더에서, global 서버는 현재 디렉터리에서 시작합니다. 이는 Agent가 하는 것처럼 서버의 코드를 사용자 컴퓨터에서 실행하므로, 신뢰하는 서버에만 --live를 사용하세요. Skillshare는 server/discover를 보냅니다. MCP 프로토콜 error가 아닌 error로 응답하거나 제한 시간의 3분의 1 안에 응답하지 않는 서버는 MCP 2026-07-28보다 오래된 것으로 간주되어 대신 initialize 핸드셰이크를 받습니다. 그런 다음 Skillshare는 tools/list를 호출해 도구 수를 세고 서버를 중지합니다: stdin을 닫은 뒤, 서버의 프로세스 그룹에 SIGTERM, 이어서 SIGKILL을 보냅니다. Windows에서는 프로세스를 종료합니다.
• 원격 (Streamable HTTP) 서버. Skillshare는 서버의 headers와 bearerToken을 사용해 server/discover를 POST하며, JSON 또는 SSE 응답을 읽습니다. MCP error가 없는 400, 404, 405는 initialize로 대체됩니다. 401은 warning ("sign-in required")이며, WWW-Authenticate 헤더의 resource metadata URL을 함께 표시합니다. Skillshare는 로그인하거나 OAuth를 시작하지 않습니다.

각 서버에는 프로브 전체에 대한 하나의 제한 시간이 있습니다: 10초, 또는 --timeout (예: 30s나 1m). 최대 네 개의 서버를 동시에 프로브합니다. --live 없이 --timeout을 쓰면 error입니다.

결과	수준
서버가 응답함: 이름과 버전, 프로토콜 버전, 도구 수	info
원격 서버가 로그인을 요구함 (HTTP 401)	warning
명령을 시작할 수 없거나, 일찍 종료되었거나, 제한 시간 안에 응답하지 않음	error
프로토콜 error, 지원되지 않는 프로토콜 버전, 또는 그 밖의 HTTP 상태	error

로컬 서버가 실패하면 메시지 끝에 해당 서버 stderr의 최대 다섯 줄이 붙습니다. env, headers, bearerToken의 값은 모든 메시지에서 제거되며, 네 글자보다 짧은 값은 그대로 남습니다. 값은 작성된 그대로 전달됩니다: Skillshare는 Pi !command 값을 실행하지 않으며 piOptions를 읽지 않습니다. 종료 코드는 같은 규칙을 따르며, error가 하나라도 있으면 1입니다. --live는 파일도, 작업 로그 항목도 쓰지 않습니다.

--json을 사용하면 응답한 서버에는 live 객체도 추가됩니다:

{
  "name": "docs",
  "ok": true,
  "findings": [
    { "level": "info", "check": "live", "target": "", "message": "responds: docs-server 1.4.0, protocol 2026-07-28, 12 tool(s)", "subject": "docs-server" }
  ],
  "live": { "protocolVersion": "2026-07-28", "serverInfo": { "name": "docs-server", "version": "1.4.0" }, "tools": 12 }
}

serverInfo는 서버가 스스로에 대해 밝힌 내용이며, 아무것도 이를 검증하지 않습니다. 서버를 프로브하지 않았거나 프로브가 실패하면 live는 생략됩니다.

대시보드의 검사 버튼은 정적 검사만 실행합니다. 대시보드가 서버를 프로브하는 곳은 한 군데뿐입니다: 서버 대화상자의 도구 섹션에 있는 도구 불러오기로, 대화상자의 현재 입력값으로 서버를 한 번 시작해 도구 목록을 가져옵니다. --json을 사용하면 live에는 tools/list가 반환한 이름인 toolNames도 들어갑니다.

Stop managing a server

skillshare mcp remove docs --keep-files

source에서 docs를 제거하고, Skillshare가 이 서버를 위해 작성한 Agent 항목의 기록을 지웁니다. Agent 파일은 바뀌지 않습니다. 이후 그 항목은 사용자의 것이며, sync는 이를 제거하지도 업데이트하지도 않습니다. --keep-files는 --sync와 함께 쓸 수 없습니다. 터미널 remove wizard는 이를 Stop managing으로 제공하며, MCP 페이지와 프로젝트의 MCP 탭에 있는 대시보드 제거 대화상자도 마찬가지입니다.

제거한 범위만 바뀝니다. global 서버의 관리를 멈춰도 같은 이름의 프로젝트 서버는 계속 관리되며, 반대도 마찬가지입니다. 항목을 다시 관리하려면 import하세요.

Servers Skillshare does not manage

대시보드는 현재 범위의 Agent 설정 파일과 mcp.projects 아래 모든 폴더의 Agent 설정 파일에서, 이 source가 정의하지 않고 어떤 Skillshare 설정도 관리하지 않는 서버를 찾습니다. 찾으면 서버 목록 위의 안내가 몇 개인지, 어느 Agent에 있는지 알려줍니다. Import는 그중 첫 번째 Agent가 선택된 상태로 import를 엽니다. 프로젝트의 MCP 탭은 그 프로젝트 자체 파일에 대해 같은 안내를 표시하며, 그 import는 프로젝트의 파일을 읽어 서버를 그 프로젝트에 저장합니다. Goose의 내장 확장처럼 연결할 대상이 없는 항목은 세지 않습니다.

Take over an entry an Agent already has

Agent 파일이 이미 사용하는 이름으로 서버를 추가하면, sync는 그 항목을 덮어쓰지 않습니다. plan은 existing entry is not managed 충돌을 보고하고, 그 항목에 대해 선택할 때까지 파일을 쓰지 않습니다:

• 그 Agent에서 import: skillshare mcp import NAME --from CLIENT, 또는 대시보드에서 충돌의 Import from 버튼(예: Import from Cursor). source와 일치하는 항목은 그대로 채택됩니다. mcp.projects 아래 폴더의 충돌이라면 버튼은 그 폴더의 파일을 읽고 해당 project로 가져옵니다.
• source 정의로 교체: 대시보드의 Replace with source, 또는 import의 --replace.

Serve skills over MCP

skillshare mcp serve                                  # stdio, every enabled skill
skillshare mcp serve --target claude                  # only the skills the claude target selects
SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \
  --tls-cert cert.pem --tls-key key.pem               # HTTPS for other machines

mcp serve는 skill이 동기화되는 폴더에 접근할 수 없는 Agent(일회용 VM에 있거나 MCP 게이트웨이 뒤에 있는 Agent 등)를 위한 읽기 전용 MCP 서버입니다. Skills extension (io.modelcontextprotocol/skills, SEP-2640)의 skills/list, skills/get, resources/read를 구현합니다. 각 skill은 하나의 항목이며, URI는 skill://_team/tools/pdf/SKILL.md처럼 source 경로를 따릅니다. 전체 frontmatter와 함께 모든 파일이 sha256 digest 및 크기와 함께 제공됩니다. 내 컴퓨터의 Agent는 이미 sync로 skill을 받으므로, 여기에 mcp serve까지 연결하면 각 skill이 두 번 보입니다.

대부분의 Agent는 아직 Skills extension을 지원하지 않으므로(아래 참고), 서버는 도구 두 개도 제공합니다. list_skills는 이름, 설명, URI를 나열하며(query로 좁힐 수 있고, 한 번의 응답에 최대 200개), read_skill은 skill의 SKILL.md나 다른 파일을 읽고, SKILL.md를 읽을 때는 그 skill의 다른 파일 목록도 보여 줍니다. MCP 도구를 사용하는 Agent라면 도구를 그대로 전달하는 게이트웨이를 거쳐도 이 방식으로 skill을 읽을 수 있습니다. Skills extension을 선언한 client는 skill을 네이티브로 로드하며 도구를 제공받지 않으므로 각 skill이 두 번 보이지 않습니다. 도구로 읽은 내용은 Agent에게 일반 텍스트이며, Agent 자체의 skill 승인은 적용되지 않습니다.

• 선택. --target 없이 실행하면 활성화된 모든 skill을 제공합니다. --target NAME은 sync mode와 관계없이 해당 target의 include/exclude 필터와 frontmatter targets를 적용합니다. skill은 항상 source에서 가져옵니다. skills가 꺼진 target을 지정하면 오류입니다.
• 건너뛰는 skill. 다음 경우 skill은 stderr에 경고를 출력하고 건너뜁니다: SKILL.md가 링크이거나 frontmatter로 시작하지 않을 때, name이 Agent Skills 명명 규칙을 어기거나 디렉터리 이름과 다를 때 (예: install --name 이후), description이 없거나 1,024자를 넘을 때, compatibility가 비어 있거나 500자를 넘을 때, 파일이 512개 또는 16 MiB를 넘을 때, 제공되지 않는 중첩 skill을 포함할 때. skillshare mcp serve --check는 같은 선택 플래그로 그런 skill과 사유를 나열하고, 서버를 시작하지 않고 종료합니다.
• 변경 사항. source는 최대 5초마다 다시 읽으므로 install, update, enable, disable이 재시작 없이 반영됩니다. 결과에는 ttlMs: 5000이 포함됩니다.
• 범위. 서버를 어디서 시작하든 기본값은 global입니다. -p는 현재 디렉터리의 project를 제공합니다.
• 전송. 기본값은 stdio이며, 명령을 시작하는 게이트웨이나 Agent에 사용합니다. --http ADDR은 Streamable HTTP를 제공합니다. loopback이 아닌 주소에는 SKILLSHARE_MCP_TOKEN과 --tls-cert, --tls-key를 통한 HTTPS가 필요하므로 token이 네트워크를 평문으로 오가지 않습니다. token이 설정되면 모든 요청은 Authorization: Bearer <token>을 보내야 합니다. TLS 프록시를 대신 쓰려면 127.0.0.1:8765 같은 loopback 주소에 바인딩하고 프록시가 TLS를 종료하게 하세요.
• 안전. skill manifest에 있는 파일만 읽을 수 있으며, 읽기는 skill 디렉터리 안으로 제한됩니다. 링크와 .git은 나열되지도 제공되지도 않습니다. 아무것도 실행하거나 쓰지 않습니다. --http에서는 cross-origin 브라우저 요청을 거부합니다.

Agent를 연결하려면 다른 서버와 똑같이 추가하고 sync하세요. Agent를 실행하는 컴퓨터에서:

skillshare mcp add skillshare --target codex --sync -- skillshare mcp serve --target codex

대시보드에서는 Add server → Skillshare가 선택한 skill로 같은 명령을 만듭니다(project mode에서는 -p 포함). Agent를 체크하고 저장한 뒤 sync하세요. 그 서버를 편집하면 같은 탭이 열립니다.

다른 컴퓨터의 Agent라면 skill이 있는 곳에서 인증서와 함께 mcp serve --http를 실행하고, 원격 서버가 그곳을 가리키게 하세요. token은 환경 변수에 두세요:

mcp:
  servers:
    skillshare:
      url: https://skills-host:8765/
      bearerToken: { fromEnv: SKILLSHARE_MCP_TOKEN }
      targets: [codex]

skill을 네이티브로 로드하려면 Skills extension이 필요합니다. 2026년 10월 기준 일반적인 코딩 Agent는 아직 이를 지원하지 않으므로 도구를 사용합니다. Codex, Cursor, VS Code, Goose, Pi는 지원하지 않으며, Claude Code는 기본적으로 켜져 있지 않은 지원을 포함합니다. mcpc, fast-agent, MCP Inspector 같은 소수의 client만 지원하며, 일부는 부분적으로만 지원합니다. SEP의 프로토타입 host 목록(예: Codex fork)이 출시된 Agent의 지원을 의미하지는 않습니다. 현재 client는 extension support matrix에서 확인하세요.

서버 자체를 확인하려면 MCP Inspector 2.6.0 이상이 모든 skill을 읽고, frontmatter를 비교하며, 각 파일의 digest를 확인합니다:

npx @modelcontextprotocol/inspector --cli skillshare mcp serve --method skills/list --verify

Safety and limitations

• JSONC 주석과 관련 없는 설정은 보존됩니다. 변경된 소유 항목은 하나의 단위로 교체되므로, 해당 항목 안의 주석은 바뀔 수 있습니다. Skillshare가 작성하는 필드만 비교되고 교체되며, 타임아웃 같은 Agent 고유 필드는 유지됩니다. "type": "stdio", 빈 env, 헤더 이름 대소문자처럼 Agent가 채우는 기본값은 변경으로 간주되지 않습니다. enabled: false나 disabled: true로 관리되는 서버를 끄는 것은 충돌로 보고됩니다. Pi와 OMP는 예외입니다. 연결 항목에서 enabled만 변경하면 소유권 충돌이 발생하지 않습니다. 동기화 시 source의 piOptions.enabled가 우선합니다.
• Claude Code가 ~/.claude.json에서 하는 것처럼 Agent가 같은 파일의 관련 없는 설정을 다시 쓰는 동안에도 미리보기는 유효하게 유지됩니다. 해당 파일의 MCP 항목이 변경된 경우에만 새 미리보기가 필요합니다.
• Codex와 Grok 편집은 일반적인 [mcp_servers.NAME] 테이블과 그 하위 테이블을 지원합니다. 업데이트된 항목은 제자리에 유지되며, CRLF 줄바꿈도 유지됩니다. 인라인/점 표기 MCP 정의는 작성하기 전에 테이블로 변환해야 하며, 그렇지 않으면 파일을 수정하지 않고 거부됩니다.
• 네이티브 파일 symlink, 손상된 파일, 중복 JSON 속성은 쓰기를 차단합니다. symlink된 Skillshare config.yaml은 그 대상으로 전달되어 작성됩니다. 단, 프로젝트에서는 실제 위치가 프로젝트 밖인 프로젝트 설정이나 sources.mcp 파일에 쓰기를 거부합니다. 파일 권한은 보존되며, 새 네이티브 파일, 소유권 기록, 백업은 private 권한을 사용합니다.
• source와 이미 일치하는 항목은, 예를 들어 팀원의 변경 사항을 pull한 후처럼, 쓰기 없이 unchanged로 보고됩니다. 어떤 Agent에서 import한 뒤 그 Agent를 선택한 경우처럼 이 구성이 이전에 이를 관리하지 않았다면 plan에 adopt가 표시됩니다: sync는 파일을 바꾸지 않고 항목을 관리 대상으로 기록하며, 이후 서버를 제거하거나 그 Agent 선택을 해제하면 항목도 제거됩니다. Agent에서 직접 끈 서버는 계속 사용자의 것입니다. 다른 unmanaged 항목은 import나 명시적인 항목별 replace가 필요합니다. 소유하는 구성 파일이 여전히 존재하는 동안에는 다른 Skillshare 구성의 소유권을 재정의할 수 없습니다. 그 파일이 사라진 경우에는 그 항목을 영원히 해제할 수 없으므로, 충돌은 해당 항목이 남겨진 항목임을 알리고 그 파일의 이름을 표시하며, 터미널에서든 대시보드의 충돌에서든 명시적인 import나 replace로 이를 가져옵니다. 마운트되지 않은 드라이브에 있는 파일처럼 읽기만 불가능한 경우는 여전히 소유자가 존재하는 것으로 간주됩니다.
• 대시보드의 MCP 설정은 브라우저가 localhost나 IP 주소로 대시보드를 열 때만 동작합니다. 리버스 프록시를 포함한 도메인 이름을 통하면 MCP 요청은 403을 반환합니다. DNS rebinding 공격은 항상 도메인 이름을 사용하기 때문입니다.
• 자격 증명은 환경 참조를 사용합니다. 시크릿 저장소, OAuth 세션 동기화, 지속적인 상태 모니터링, 패키지 설치, 게이트웨이, 레지스트리, 플러그인 동기화는 없습니다. 구성된 서버를 시작하거나 호출하는 명령은 mcp check --live뿐입니다. mcp serve는 Skillshare 자체의 읽기 전용 skills 서버를 실행합니다.
• VS Code Insiders, 사용자 지정 프로필, 원격 워크스페이스, 레거시 SSE는 이 버전에서 지원되지 않습니다.
• VS Code는 현재 headers 안에서 ${env:VARIABLE}을 치환하지 않으므로 (microsoft/vscode#336232), VS Code로 동기화된 헤더와 bearerToken 참조는 해당 문제가 수정될 때까지 서버에 해석되지 않은 채로 도달합니다.
• 로컬 작업 기록은 Skillshare state 디렉터리의 mcp/ 아래에 존재합니다: state.json, 쓰기 중의 pending.json, 그리고 backups/(Agent 파일별 최신 20개). 이 디렉터리를 이식 가능한 매니페스트로 공유하지 마세요.

도구 정책

tools는 서버의 도구 중 어떤 것이 모델에 전달되는지 정합니다. 서버에 한 번만 작성하면, Skillshare가 sync할 때 각 Agent 고유의 필드로 변환합니다.

mcp:
  servers:
    github:
      command: github-mcp
      targets: [pi, codex, copilot, opencode]
      tools:
        allow: [get_*, search_code, list_issues]
        deny: [get_secret]

skillshare mcp add github --target pi --target codex --tools-allow 'get_*,search_code' --tools-deny get_secret -- github-mcp
skillshare mcp edit github --tools-allow ''          # clear the allow list
skillshare mcp import github --from claude --target pi --tools-deny get_secret

Field	Meaning
allow	설정하면 일치하는 도구만 남습니다
deny	일치하는 도구를 제거하며, allow와 일치하더라도 제거됩니다

allow와 deny의 항목은 도구 이름이며, *는 임의의 문자와 일치합니다. 그 밖의 와일드카드(? [ ] { }), 공백, 쉼표는 거부되며, 같은 이름을 두 번 적어도 거부됩니다. allow가 남긴 도구를 모두 제거하는 deny 목록은 오류입니다. disabled 항목에는 tools를 설정할 수 없습니다. 두 flag는 mcp add, mcp edit, mcp import에서 동작합니다. 목록은 쉼표로 구분하며, 빈 값은 해당 부분을 지웁니다. Pi가 도구를 어떻게 제공하는지는 정책에 포함되지 않습니다. 이는 Pi의 exposure이며 piOptions에서 설정합니다.

각 Agent가 받는 내용

모든 Agent가 정책의 모든 부분을 담을 수 있는 것은 아닙니다. Skillshare는 Agent의 문서화된 형식이 지원하는 부분을 작성하고 나머지는 알려줍니다. 어떤 부분도 조용히 버리지 않습니다.

Agent	작성되는 내용	적용되지 않는 부분
Pi	toolExposure에는 거부된 도구를 hidden으로, 이어서 허용된 도구를, allow가 설정되어 있으면 마지막에 "*": "hidden"을 작성	없음
Codex	enabled_tools와 disabled_tools, 정확한 이름만. Codex는 enabled_tools 다음에 disabled_tools를 적용합니다	allow의 * 패턴; 정확한 allow 목록으로 합칠 수 없는 deny의 * 패턴
Copilot CLI	tools: 허용된 정확한 이름에서 거부된 이름을 뺀 것, 그렇지 않으면 ["*"]	allow의 * 패턴; allow가 정확한 이름을 나열하지 않을 때의 deny(Copilot에는 거부 목록이 없음)
OpenCode, Kilo Code	없음	전부. 둘 다 서버 항목 밖의 최상위 permission 맵에서 <server>_<tool> 키로만 도구를 거릅니다
그 밖의 모든 Agent	없음	전부

Pi에서는 정확한 도구 이름이 어떤 패턴보다 우선하므로, 거부된 패턴과 일치하는 허용된 정확한 이름은 toolExposure에서 빠집니다. 허용된 도구는 서버의 piOptions.exposure를 받으며, 그것이 설정되지 않았거나 hidden이면 Pi 기본값인 codemode를 받습니다. 따라서 allow와 함께 쓴 hidden은 허용된 도구만 보인다는 뜻입니다.

적용되지 않는 부분은 세 곳에 표시됩니다:

• sync plan에서, Agent마다 서버를 나열하는 warning 줄로:

  ! tool policy not applied for opencode: allow, deny (github)

  --json을 사용하면 같은 텍스트가 plan의 notices에 들어갑니다.

• mcp check에서, 각 Agent에 대한 tools warning으로.

• 대시보드에서, 서버 대화상자의 도구 섹션과 각 Agent에 기록될 설정 보기에서. 대시보드는 이것들이나 아래의 폐지된 Pi 설정에 대해 페이지 수준 알림을 표시하지 않습니다.

Codex의 enabled_tools와 disabled_tools는 관리되는 필드입니다: 정책을 지우면 함께 제거되며, Skillshare가 소유한 항목에서 직접 편집하면 충돌로 표시됩니다. import는 Codex의 enabled_tools/disabled_tools와 Copilot의 tools를 다시 tools로 읽어옵니다. Pi의 toolExposure는 서버의 exposure와 함께 그 정책을 작성했을 때 정확히 같은 toolExposure가 나오는 경우에만 tools가 되며, 그렇지 않으면 warning과 함께 piOptions에 남습니다. exposure는 항상 piOptions에 남습니다.

대시보드의 도구

서버 대화상자에는 target 다음에 도구 섹션이 있으며, disabled 항목을 제외한 모든 서버에 표시됩니다. 이 섹션은 항상 표시됩니다. 제목 옆의 정보 아이콘이 섹션을 설명하고, 요약에는 모든 도구, 정책 내용(예: 1개만 허용, 2개 제외), 또는 도구를 불러온 뒤의 9 / 14 선택됨이 표시됩니다.

• 제목 아래 상자에 도구 목록이 들어갑니다. 불러오기 전에는 도구 불러오기가 있으며, 저장 여부와 관계없이 대화상자의 현재 설정으로 서버를 mcp check --live와 같은 프로브로 한 번 시작합니다. 클릭할 때만 실행되고 아무것도 저장하지 않으므로 새 서버에서도 쓸 수 있습니다. 실패하면 이유를 쉬운 말로 보여 주고, 원래 오류는 옆의 정보 아이콘 툴팁에 있으며, 버튼은 다시 시도로 바뀝니다. 이후 명령, URL 또는 관련 설정을 바꾸면 불러온 목록은 지워집니다.
• 불러오면 도구마다 체크박스가 생기고, 선택한 도구만 모델에 전달됩니다. 선택을 해제하면 그 도구의 정확한 이름이 deny에 추가됩니다. 다시 선택하면 그 이름이 deny에서 빠지고, 비어 있지 않은 allow가 여전히 제외하면 allow에 이름이 추가됩니다. deny 패턴이 제거하는 도구는 선택할 수 없으며, 툴팁이 해당 규칙을 알려 줍니다. 검색 상자로 목록을 거를 수 있고, 모두 선택과 모두 해제는 보이는 행에만 적용되며, 새로고침 버튼은 목록을 다시 불러옵니다.
• 상자 아래쪽의 제외 규칙 행에는 * 패턴과 서버가 나열하지 않는 이름을 입력합니다. 하나를 입력하고 Enter를 누르세요. allow에 항목이 있으면 그 위에 같은 방식의 허용만 행이 있습니다. 도구를 불러오기 전에는 저장된 항목이 모두 여기에 표시됩니다. 잘못된 이름이나 허용된 도구를 모두 제거하는 거부 목록은 대화상자에 표시되며 저장을 막습니다.
• 그 아래에서 대화상자는 선택된 각 Agent가 실제로 무엇을 받는지 알려 줍니다: 이 목록대로 제공하는 Agent, 일부만 적용하는 Agent의 동작(예: Copilot CLI는 거부 목록이 없어 선택 해제한 도구도 제공), 그리고 필터링을 지원하지 않는 Agent입니다.

서버 행에는 정책을 쉬운 말로 나타내는 태그(예: 도구: 도구 2개 제외)가 표시되며, 각 Agent에 기록될 설정 보기는 Agent마다 적용하지 않는 부분을 경고합니다.

Oh My Pi (OMP)

omp는 Pi와 별개의 client입니다. Skillshare는 명시적인 type: stdio 또는 type: http와 ${VARIABLE} 환경 참조를 사용해 OMP의 네이티브 mcpServers 맵을 작성합니다. OMP를 대신해 .pi/, Claude, Codex 구성에 쓰지 않습니다. 서버 이름은 최대 100자여야 합니다.

skillshare mcp add docs --url https://example.com/mcp --target omp -g --sync --no-tui
skillshare mcp import docs --from omp --target omp -g --replace --dry-run --json

sync는 $schema, disabledServers, enabledServers와 관련 없는 서버를 보존합니다. 기존 연결을 업데이트할 때 enabled, timeout, instructions, requestIdFormat, cwd, auth, oauth 같은 서버별 네이티브 필드도 유지합니다. 이 필드는 piOptions가 아니며, Pi 전용 설정은 OMP로 전달되지 않습니다. import는 이식 가능한 모델로 표현할 수 없는 네이티브 필드에 대해 경고합니다. 그런 필드는 OMP의 파일에 유지하세요. 이식 가능한 모델은 stdio와 Streamable HTTP를 지원하지만 OMP의 레거시 SSE 전송은 지원하지 않습니다. 지원되지 않는 import는 변환하지 않고 거부합니다.

disabledServers는 enabledServers와 항목의 enabled 값보다 우선합니다. sync는 서버를 활성화하기 위해 사용자의 denylist 항목을 제거하지 않습니다. import는 disabledServers나 enabled: false로 숨겨진 서버를 거부합니다. 단, 후자가 enabledServers로 강제 활성화된 경우는 예외입니다. OMP의 schema나 enable/disable 목록이 있는 JSON은 importer에 붙여 넣으면 OMP로 인식됩니다.

OMP는 !로 시작하는 env/header 값을 shell 명령으로 실행할 수 있습니다. Skillshare는 그런 리터럴을 내보내거나 해당 자격 증명을 import하는 것을 거부하며, 이를 실행하지 않습니다. source에서는 {fromEnv: VARIABLE}, 네이티브 JSON에서는 ${VARIABLE}을 사용하세요. "TOKEN": "TOKEN"처럼 같은 이름의 bare env 참조는 fromEnv로 import됩니다. 이식 가능한 참조에는 리터럴 fallback이 없으므로 연결하기 전에 변수를 설정하세요. 그 밖의 client 고유 보간은 import하기 전에 변환해야 합니다.

global MCP는 PI_CODING_AGENT_DIR을 따르며, project MCP는 .omp/mcp.json으로 유지됩니다. Pi도 같은 환경 변수를 사용하므로 둘을 같은 파일로 동기화하는 것은 거부됩니다. 별도의 디렉터리나 명시적인 계정 target을 사용하세요. named profile과 PI_CONFIG_DIR의 자동 경로 선택은 관리하지 않습니다. 그 profile에는 agent: omp와 config_dir: ~/.omp/profiles/work/agent로 target을 선언하세요. 계정 target은 global 전용이며, project 정의에는 omp를 사용합니다.

편집하거나 sync한 뒤 OMP에서 /mcp reload를 실행하고 /mcp list로 source와 연결 상태를 확인하세요. 승인과 OAuth 로그인은 계속 OMP가 담당합니다.

Pi

Pi ≥ 0.99.0에는 MCP가 내장되어 있으며, Skillshare가 Pi에 MCP 서버를 작성하는 방법은 이것뿐입니다. 서드파티 pi-mcp-adapter와 pi-mcp-extension은 더 이상 sync 대상으로 지원되지 않습니다.

Scope	File
Global	~/.pi/agent/mcp.json (PI_CODING_AGENT_DIR을 존중)
Project	.pi/mcp.json

개인 서버와 자격 증명이 있는 서버는 ~/.pi/agent/mcp.json에 두세요. .pi/mcp.json은 신뢰하는 프로젝트에서 그 프로젝트에 필요한 서버에만 사용하세요. 같은 이름의 project entry는 global entry 전체를 대체합니다. Skillshare는 미리 보기와 백업을 제공하며 파일을 직접 편집합니다. 프로젝트 신뢰, 서버 실행, 확장 설치, OAuth 인증은 처리하지 않습니다.

skillshare mcp add docs --url https://example.com/mcp --target pi --tools-deny 'delete_*' --pi-options '{"exposure":"deferred","timeout":120}' --no-tui
skillshare sync mcp --dry-run
skillshare sync mcp

mcp:
  servers:
    docs:
      url: https://example.com/mcp
      targets: [pi]
      tools:
        deny: [delete_*]
      piOptions:
        exposure: deferred
        timeout: 120

네이티브 출력은 command/args 또는 url을 사용하며, 환경 참조는 ${NAME}입니다. sync 후에는 /reload를 실행하거나 새 Pi 세션을 시작하고, /mcp로 연결을 확인하고 OAuth를 승인하세요. 간단한 Pi 전용 설정에는 pi mcp add가 global 파일을 편집하며, project에는 -l을 추가하세요. pi mcp list는 활성 서버를 모두 시작해 연결을 확인하며, pi mcp login NAME은 사용자 승인이 필요합니다.

Pi 서버 이름에는 영문자, 숫자, _, -만 쓸 수 있습니다. -와 _만 다른 이름은 Pi가 같은 서버로 읽으므로 sync는 두 번째 이름을 거부합니다. Pi에서는 프로젝트 항목이 같은 이름의 global 항목을 통째로 대체합니다. 한 프로젝트에서 global 서버를 끄려면 Turn off a global server in one project를 참고하세요.

Pi 1.0.1부터 Pi의 /mcp는 enabled, exposure, toolExposure만 있는 프로젝트 항목을 추가해 같은 이름의 global 서버를 덮어쓸 수 있습니다. 이 항목은 서버가 아니므로 가져오기에서 건너뜁니다. disabled 항목도 같은 덮어쓰기를 쓰므로, 정확히 {"enabled": false}인 덮어쓰기는 충돌이 아닙니다. sync가 스위치를 쓴 뒤 Pi에서 추가한 exposure 같은 Pi 설정은 sync가 관리하는 다른 Pi 항목처럼 유지되고, Pi에서 서버를 다시 켜면 충돌입니다. 프로젝트가 같은 이름의 서버를 정의하거나, sync가 쓰지 않은 덮어쓰기가 disabled 항목과 다르면, 그 항목을 대체하거나 Pi에서 덮어쓰기를 제거할 때까지 sync가 충돌을 보고합니다.

Pi 1.0.4의 --no-mcp는 해당 실행에서 MCP를 비활성화합니다. --tools는 항목이 mcp__로 시작할 때만 MCP 도구를 필터링합니다. 동기화 후 서버를 사용할 수 없다면 이 실행 인수를 확인하세요.

기타 Pi 설정

piOptions는 Pi 내장 MCP의 그 밖의 서버별 필드를 담습니다. Pi만 이를 받습니다.

• oauth.clientRegistration은 dcr(Pi 기본값) 또는 cimd(Pi 1.0.1 이상)를 허용합니다. cimd에서는 clientId와 clientName을 지정할 수 없습니다. callbackUrl은 HTTP, 호스트는 localhost 또는 127.0.0.1, 경로는 /callback이어야 합니다. 인증 서버는 공개 클라이언트의 CIMD를 지원해야 합니다.
• exposure는 codemode(Pi 기본값), codemode-deferred(codemode의 이전 이름), deferred, direct, hidden을 받습니다. toolExposure는 도구 이름이나 와일드카드 패턴을 이 값 중 하나에 대응시킵니다: 정확한 이름이 우선하고, 그다음 처음 일치하는 패턴이 적용됩니다. Skillshare는 import와 JSON/YAML 변환에서 패턴 순서를 유지합니다. exposure는 tools 허용 목록이 남긴 도구를 어떻게 제공할지도 정합니다. toolExposure보다 다른 Agent에도 전달되는 tools를 우선 사용하세요. 한 서버에 tools와 toolExposure를 함께 설정할 수는 없습니다.
• timeout(양수 초), cwd, enabled, oauth, auth는 검증됩니다. description 같은 알 수 없는 필드는 그대로 전달됩니다.
• auth: {provider: NAME}은 해당 provider의 /login 토큰을 bearer 토큰으로 보냅니다. https url(localhost는 http도 가능)이 필요하며, Pi가 global 파일에서만 읽으므로 global 모드에서만 쓸 수 있습니다.
• oauth.authServerMetadataUrl(Pi 1.0 이상)은 https(localhost는 http도 가능)여야 합니다. Pi가 자동 탐색 대신 이 문서를 그대로 신뢰하기 때문입니다. Pi 1.0은 OAuth 로그인을 server 이름과 URL별로 저장하므로, server 이름이나 url을 바꾼 뒤에는 Pi에서 다시 로그인해야 합니다.
• 연결 필드는 메인 폼에 둡니다. directTools, includeTools, excludeTools와 그 밖의 pi-mcp-adapter 설정은 Pi 내장 MCP가 읽지 않으므로 거부됩니다. 대신 tools를 사용하세요.
• 최상위 settings와 autoEnableCodemode는 서버 옵션이 아닙니다: Pi에서 직접 편집하세요. sync는 이를 유지합니다.
• 자격 증명은 환경 참조로 두세요. 이식 가능한 env/headers의 !command 리터럴 값은 거부되며, oauth.clientId 같은 비밀이 아닌 필드를 포함해 piOptions 어디에서든 명령 값은 거부됩니다.

JSON을 지우거나 JSON에서 필드를 제거하면, Skillshare가 작성했고 변경되지 않은 필드는 다음 sync에서 Pi 파일에서도 제거됩니다. Pi에서 직접 추가한 필드는 유지됩니다. Skillshare가 작성한 뒤 Pi에서 변경된 필드는 import할 때까지 sync를 막습니다.

skillshare mcp edit docs --pi-options '{"timeout":60}' --no-tui
skillshare mcp edit docs --pi-options '{}' --no-tui

대시보드에서는 서버 대화상자의 Pi 블록에 도구 노출 모드와 기타 Pi 설정이 있습니다. Pi 설정과 도구 노출 모드 옆의 정보 아이콘이 이를 설명하며, Pi 설정 옆의 링크는 Pi의 MCP 문서를 엽니다. 대화상자는 저장하기 전에 기타 Pi 설정의 pi-mcp-adapter 필드를 표시해 줍니다. 도구 섹션에 설정이 있어도 도구 노출 모드는 편집할 수 있습니다. 이때는 tools가 작성하는 기타 Pi 설정의 toolExposure만 거부됩니다. 서버 행의 Pi 칩은 노출 모드를 짧은 말로 보여 줍니다(예: codemode는 코드로 호출).

0.22에서 Pi 업그레이드하기

업그레이드 후 첫 sync 전에 Pi에서 두 가지를 확인하세요.

• Pi 0.99.0 이상. Skillshare는 이제 Pi의 서버를 mcp.json에만 작성하며, Pi는 0.99.0에서 추가된 내장 MCP로 이 파일을 읽습니다. 이전 Pi는 이 파일을 읽지 않으므로 Pi를 업데이트할 때까지 이 서버들은 로드되지 않습니다. Skillshare는 Pi 버전을 확인하지 않습니다.
• pi-mcp-adapter 또는 pi-mcp-extension이 아직 설치되어 있다면 Pi에서 제거하세요. Pi의 MCP 문서에 따르면 /mcp를 등록하는 extension이 설치되어 있으면 내장 MCP를 대체합니다. pi-mcp-extension은 mcp.json도 직접 읽고, pi-mcp-adapter는 3.0.0부터 이 파일을 읽지 않으므로 Skillshare가 옮긴 서버는 adapter를 통해 로드되지 않습니다.

sync가 서버를 이 extension들에서 옮길 때 sync mcp --dry-run, sync mcp, --json은 한 번 다음과 같이 알립니다.

! Pi's built-in MCP needs Pi 0.99.0 or later; on older Pi these servers stop loading until Pi is updated. If pi-mcp-adapter or pi-mcp-extension is still installed in Pi, remove it, because it can take the place of Pi's built-in MCP

이 알림은 sync가 Skillshare가 mcp-adapter.json에 작성한 항목을 제거하거나, pi-mcp-extension용으로 작성한 항목을 다시 쓰거나, 이 extension들만 읽는 설정(piExtension: pi-mcp-adapter 또는 pi-mcp-extension, directTools, 아래에 나열된 piOptions 필드)을 찾을 때 나타납니다. 그 sync 이후에는 나타나지 않습니다.

0.23.0에서는 Pi 모드 선택(piExtension: builtin, pi-mcp-adapter, pi-mcp-extension), piOptionsPrune 스위치, directTools가 제거되었습니다. 이전 config도 그대로 로드됩니다. sync mcp --dry-run과 sync mcp는 발견한 폐지된 설정의 종류마다 서버 이름을 담은 warning을 출력합니다. 예:

! Pi now uses its built-in MCP; the next sync updates the config: context7, local (shop)

mcp.projects 아래의 프로젝트에서만 발견된 서버는 괄호 안에 프로젝트 폴더가 표시됩니다.

다음 sync가 하는 일:

0.23.0 이전	sync 이후
piExtension: builtin	키가 제거됩니다. 그 밖에는 바뀌지 않습니다
piExtension: pi-mcp-extension	키가 제거됩니다. 항목이 이미 mcp.json에 있었으므로 그 자리에서 내장 형식으로 다시 작성됩니다
piExtension: pi-mcp-adapter	키가 제거됩니다. 서버는 mcp.json에 작성되고, Skillshare가 mcp-adapter.json에 작성한 항목은 제거됩니다. mcp-adapter.json에 직접 추가한 항목은 그대로 둡니다
piOptionsPrune	키가 제거됩니다. sync는 Skillshare가 작성했고 변경되지 않은 지워진 필드를 항상 제거합니다(위)
서버의 directTools	true → piOptions.exposure: direct; "search" → deferred; 이름 목록 → 해당 도구를 direct로 둔 piOptions.toolExposure
mcp.directTools, 또는 mcp.projects 아래 프로젝트의 directTools	Pi에 전달되고 자체 값이 없는 각 서버에 기본값이 위와 같이 작성됩니다. 프로젝트의 false는 global 값을 재정의합니다
piOptions.includeTools / excludeTools	tools.allow / tools.deny가 되며, 함께 설정한 directTools는 여전히 piOptions.exposure가 됩니다
piOptions의 그 밖의 pi-mcp-adapter 필드: approveTools, 문자열 auth(Pi 자체의 auth 객체는 유지), bearerToken, bearerTokenEnv, bearerTokenStore, caFile, debug, exposeResources, idleTimeout, inheritEnv, lifecycle, protocolVersion, requestHeadersCommand, requestTimeoutMs, searchKeywords, socket, tasks, toolPrefix, trace	Pi 내장 MCP가 읽지 않으므로 제거됩니다

서버가 이미 설정한 exposure를 덮어쓰게 되거나 도구 이름 목록이 아닌 directTools, includeTools, excludeTools는 별도의 warning과 함께 버려집니다.

이 변경을 적용하는 첫 sync는 폐지된 설정을 뺀 Skillshare config도 저장합니다: config.yaml, 또는 sources.mcp가 가리키는 파일입니다. 쓰기 전에 이전 파일을 reason이 migrate인 파일 이력에 보관하고, 파일마다 한 줄을 출력합니다:

→ Updated config.yaml for 0.23.0 (backup: <path of the saved version>)

이는 skillshare sync mcp, skillshare sync --all(Agent 파일이 바뀌지 않을 때도), 대시보드의 sync에서 일어납니다. --dry-run과 미리 보기는 아무것도 쓰지 않습니다. config 저장에 실패하면 Agent 파일은 이미 작성되었고 config는 그대로 남습니다. 오류 메시지가 이를 알려주며, 다음 sync가 다시 시도합니다. 저장에 성공하면 warning은 사라집니다.

제거된 flag는 이제 메시지와 함께 실패합니다:

Flag	대신 사용할 것
--pi-extension	빼세요. Pi는 항상 내장 MCP를 사용합니다
--pi-options-prune	빼세요. sync는 Skillshare가 이전에 작성한 변경되지 않은 필드를 항상 제거합니다
--direct-tools	모든 도구에는 --pi-options '{"exposure":"direct"}', Pi에서 개별 도구에는 --pi-options '{"toolExposure":{"TOOL":"direct"}}'

skillshare mcp import --from pi는 Pi의 mcp.json과 함께 pi-mcp-adapter의 mcp-adapter.json도 계속 읽으므로, 서버를 옮겨 올 수 있습니다. 두 파일이 같은 서버를 정의하면 mcp.json이 우선합니다. sync는 서버를 Pi의 mcp.json에 작성하며, mcp-adapter.json에서는 0.23.0 이전에 자신이 작성한 항목만 제거합니다. 그 directTools, includeTools, excludeTools는 위와 같이 변환되며, 그 밖의 adapter 전용 필드는 warning과 함께 제외됩니다. 대시보드에서는 target에서 가져오기가 두 Pi 파일을 별도의 원본으로 나열합니다.