Agent Plugins 1.0으로 스킬과 MCP 서버 묶기: plugin.json·mcp.json 작성과 스키마 검사
한 번 패키징해 여러 AI 클라이언트에서 쓰는 플러그인 구조와, 공식 JSON 스키마 기준 점검 스크립트

핵심 요약
- Agent Plugins는 Agent Skills(skills/*/SKILL.md)와 MCP 서버(mcp.json)를 정해진 위치에 담는 공개 패키지 형식이다.
- plugin.json의 필수 필드는 $schema와 name뿐이며, 정의되지 않은 필드는 허용되지 않는다.
- mcp.json의 서버 type은 stdio·streamable-http·sse뿐이라 Claude Code의 "http"를 그대로 쓰면 실패한다.
- 플러그인이 읽고 실행하는 모든 파일은 플러그인 루트 안에 있어야 한다.
팀에서 만든 스킬과 MCP 서버를 Claude Code, Cursor, Copilot, Codex 등 여러 클라이언트에서 쓰려면 클라이언트마다 설정 위치와 형식을 따로 맞춰야 했다. Agent Plugins는 Agent Skills와 MCP 서버를 정해진 위치에 담는 공개 패키지 형식이다. Vercel이 제안하고 AWS, Anysphere(Cursor), GitHub, Microsoft, OpenAI, Vercel 대표가 함께 다듬어 2026년 8월 1.0.0으로 공개했다. 이 글은 Vercel 가이드와 공식 JSON 스키마(2026-10-07 확인)를 기준으로 플러그인 구조와 점검 방법을 정리한다.
플러그인 구조
team-release-tools/
├─ plugin.json # 필수: 매니페스트
├─ mcp.json # 선택: MCP 서버 설정
├─ skills/
│ └─ release-notes/
│ └─ SKILL.md # 스킬마다 필수
├─ server/index.mjs # mcp.json이 실행하는 서버 코드
└─ com.example.client/ # 선택: 특정 클라이언트 전용 확장(역도메인 이름)
| 파일 | 규칙 |
|---|---|
plugin.json | 필수 필드는 $schema와 name뿐. 선택 필드는 version, description, author, homepage, repository, license, keywords, extensions. 그 밖의 필드는 허용되지 않는다 |
name | 1~64자, 소문자·숫자·하이픈·마침표만. 연속된 --, .. 금지 |
skills/ | 바로 아래 하위 폴더 하나가 스킬 하나. 각 폴더에 SKILL.md 필수 |
mcp.json | 최상위에는 $schema와 mcpServers만. 서버 type은 stdio, streamable-http, sse(deprecated) |
| 경로 | 클라이언트가 찾고 읽고 실행하는 모든 파일은 플러그인 루트 안에 있어야 한다 |
파일 작성 순서
plugin.json에 스키마 주소와 이름을 먼저 적는다.- 스킬을
skills/<이름>/SKILL.md로 옮긴다. frontmatter에name과description을 둔다. - MCP 서버 설정을
mcp.json으로 옮기고, 서버 실행 파일을 플러그인 안에 넣는다. - 아래 점검 스크립트로 구조를 확인한다.
- 대상 클라이언트에 설치해 스킬과 MCP 도구가 모두 보이는지 확인한다.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "team-release-tools",
"version": "0.1.0",
"description": "릴리스 노트 작성 스킬과 사내 이슈 트래커 MCP 서버"
}
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"issue-tracker": {
"type": "stdio",
"command": "node",
"args": ["./server/index.mjs"],
"env": { "TRACKER_BASE_URL": "https://tracker.example.com" }
}
}
}
Claude Code의 .mcp.json을 그대로 옮기면 안 되는 이유
Claude Code는 프로젝트 범위 MCP 서버를 루트의 .mcp.json에 저장하고, HTTP 서버를 "type": "http"로 적는다. Agent Plugins 스키마는 서버 type으로 stdio, streamable-http, sse만 허용하고, 최상위에 $schema가 필수다. 파일 이름(.mcp.json → mcp.json)과 함께 이 두 가지를 바꿔야 한다. 또 env에는 PLUGIN_ROOT, PLUGIN_DATA라는 이름을 쓸 수 없고, cwd는 ./나 ${PLUGIN_ROOT}로 시작하는 플러그인 상대 경로여야 한다.
공식 스키마 기준 점검 스크립트
plugin.json 스키마와 mcp.json 스키마를 내려받아 주요 규칙을 의존성 없이 점검하는 스크립트다. 전체 JSON Schema 검증기가 아니라 자주 틀리는 규칙만 확인하는 부분 검사기이므로, 배포 전에는 JSON Schema 검증 도구로 한 번 더 확인한다.
// 사용법: node check-plugin.mjs <플러그인 폴더>
// Agent Plugins 1.0.0 공식 JSON 스키마의 주요 규칙(필수 필드, 허용 필드, 이름 패턴, MCP 서버 형식)과
// skills/*/SKILL.md 존재 여부, 플러그인 루트 밖 경로 참조를 점검한다. 의존성 없는 부분 검사기다.
import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
import { join } from 'node:path';
const root = process.argv[2];
const errors = [];
const readJson = (f) => { try { return JSON.parse(readFileSync(join(root, f), 'utf8')); } catch (e) { errors.push(`${f}: JSON 파싱 실패 (${e.message})`); return null; } };
const PLUGIN_SCHEMA = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json';
const MCP_SCHEMA = 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json';
const PLUGIN_KEYS = ['$schema', 'name', 'version', 'description', 'author', 'homepage', 'repository', 'license', 'keywords', 'extensions'];
const NAME_RE = /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
const SERVER_KEYS = { stdio: ['type', 'command', 'args', 'env', 'cwd'], 'streamable-http': ['type', 'url', 'headers'], sse: ['type', 'url', 'headers'] };
if (!existsSync(join(root, 'plugin.json'))) errors.push('plugin.json 없음 (필수)');
else {
const p = readJson('plugin.json');
if (p) {
if (p.$schema !== PLUGIN_SCHEMA) errors.push(`plugin.json: $schema는 ${PLUGIN_SCHEMA} 이어야 함`);
if (typeof p.name !== 'string' || p.name.length > 64 || !NAME_RE.test(p.name)) errors.push(`plugin.json: name "${p.name}" 형식 오류 (소문자·숫자·-·. 1~64자, 연속 --/.. 금지)`);
Object.keys(p).filter((k) => !PLUGIN_KEYS.includes(k)).forEach((k) => errors.push(`plugin.json: 허용되지 않는 필드 "${k}"`));
}
}
if (existsSync(join(root, 'mcp.json'))) {
const m = readJson('mcp.json');
if (m) {
if (m.$schema !== MCP_SCHEMA) errors.push(`mcp.json: $schema는 ${MCP_SCHEMA} 이어야 함`);
Object.keys(m).filter((k) => !['$schema', 'mcpServers'].includes(k)).forEach((k) => errors.push(`mcp.json: 허용되지 않는 최상위 필드 "${k}"`));
for (const [name, s] of Object.entries(m.mcpServers || {})) {
const allowed = SERVER_KEYS[s.type];
if (!allowed) { errors.push(`mcp.json: ${name}.type "${s.type}"은 stdio/streamable-http/sse 중 하나여야 함`); continue; }
Object.keys(s).filter((k) => !allowed.includes(k)).forEach((k) => errors.push(`mcp.json: ${name}에 허용되지 않는 필드 "${k}"`));
if (s.type === 'stdio' && !s.command) errors.push(`mcp.json: ${name}.command 필요`);
if (s.type !== 'stdio' && !s.url) errors.push(`mcp.json: ${name}.url 필요`);
if (s.type === 'sse') console.log(`참고: ${name}은 sse 전송 방식(명세상 deprecated)`);
[...(s.args || []), s.cwd || ''].filter((a) => a.includes('..') || /^([A-Za-z]:\|\/)/.test(a))
.forEach((a) => errors.push(`mcp.json: ${name}가 플러그인 루트 밖 경로를 참조 "${a}"`));
}
}
}
if (existsSync(join(root, 'skills'))) {
for (const d of readdirSync(join(root, 'skills'))) {
const dir = join(root, 'skills', d);
if (!statSync(dir).isDirectory()) continue;
const md = join(dir, 'SKILL.md');
if (!existsSync(md)) { errors.push(`skills/${d}: SKILL.md 없음`); continue; }
const fm = readFileSync(md, 'utf8').match(/^---\n([\s\S]*?)\n---/);
if (!fm || !/^name:\s*\S/m.test(fm[1]) || !/^description:\s*\S/m.test(fm[1])) errors.push(`skills/${d}/SKILL.md: frontmatter에 name·description 필요`);
}
}
console.log(errors.length ? `FAIL ${root}` : `PASS ${root}`);
errors.forEach((e) => console.log(` - ${e}`));
process.exitCode = errors.length ? 1 : 0;
올바른 예시(good)와, 흔히 틀리는 지점을 모은 예시(bad)에 2026-10-07 실행한 결과다. bad는 이름에 대문자·밑줄·연속 하이픈을 쓰고, plugin.json에 스킬 목록을 직접 적고, mcp.json에 servers 키와 Claude Code식 "type": "http"를 쓰고, 상위 폴더의 서버 파일을 참조하고, 스킬 폴더에 SKILL.md 대신 README.md만 두었다.
$ node check-plugin.mjs good; node check-plugin.mjs bad
PASS good
FAIL bad
- plugin.json: name "Team_Release--Tools" 형식 오류 (소문자·숫자·-·. 1~64자, 연속 --/.. 금지)
- plugin.json: 허용되지 않는 필드 "skills"
- mcp.json: 허용되지 않는 최상위 필드 "servers"
- mcp.json: tracker.type "http"은 stdio/streamable-http/sse 중 하나여야 함
- mcp.json: local가 플러그인 루트 밖 경로를 참조 "../shared/server.mjs"
- skills/changelog: SKILL.md 없음
plugin.json에는 스킬 목록을 적는 필드가 없다. 스킬은 skills/ 아래 폴더 구조로만 발견되므로, 목록을 적어도 클라이언트는 읽지 않고 스키마 검증만 실패한다. 스킬 자체를 설계하는 방법은 Claude Code Skills·Hooks·Subagents 차이를, 플러그인에 넣을 MCP 서버를 만드는 방법은 TypeScript로 최소 MCP 서버 만들기를 참고한다.
배포 전에 확인할 것
- 플러그인의 MCP 서버가 접근하는 시스템과 권한 범위를 README에 적는다. 플러그인을 설치하면 그 서버가 사용자의 클라이언트에서 실행된다.
- 토큰 같은 비밀값은
env에 값을 적지 않고, 클라이언트의 비밀값 설정으로 주입하게 안내한다. version을 올려 배포하고, 변경 내용을 기록한다.- 설치·배포·권한 관리 방식은 클라이언트마다 다르다. 형식은 공통이지만 설치 경험은 각 클라이언트 문서를 따른다.
초보자가 자주 실수하는 포인트
- plugin.json에 skills 목록을 직접 적는다.
- Claude Code의 .mcp.json을 이름만 바꿔 복사해 type과 $schema가 맞지 않는다.
- MCP 서버 실행 파일을 플러그인 밖 상위 폴더에서 참조한다.
- 스킬 폴더에 SKILL.md 대신 README.md만 둔다.
체크리스트
- plugin.json에 $schema와 규칙에 맞는 name이 있다.
- 스킬마다 skills/<이름>/SKILL.md와 frontmatter가 있다.
- mcp.json의 type과 최상위 필드가 스키마와 맞는다.
- 모든 참조 경로가 플러그인 루트 안에 있다.
- MCP 서버의 접근 범위와 비밀값 주입 방법을 README에 적었다.
자주 묻는 질문
어떤 클라이언트가 Agent Plugins를 지원하나요?
1.0.0 공개 당시 ChatGPT와 Codex, Cursor, GitHub Copilot, Kiro, VS Code가 지원 클라이언트로 소개됐습니다. 지원 범위는 바뀔 수 있으므로 쓰려는 클라이언트의 문서에서 현재 상태를 확인하세요.
기존 MCP 서버 코드를 고쳐야 하나요?
서버 코드는 그대로 두고 실행 방법을 mcp.json에 적으면 됩니다. 다만 서버 파일이 플러그인 루트 안에 있어야 하고, 실행 경로를 ./로 시작하는 상대 경로로 적어야 합니다.
참고 자료 · 검증 기준
- Vercel Changelog — Introducing Agent Plugins 1.0.0
- Vercel KB — Agent Plugins
- Agent Plugins — plugin.json schema 1.0.0
- Agent Plugins — mcp.json schema 1.0.0
- Claude Code Docs — MCP (project scope .mcp.json)
위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.
이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.