# 연동 워크플로 (/ko/docs/verdent-for-vscode/advanced-features/integrations)
> Verdent을 외부 도구 및 서비스와 연동하기 위한 실용 패턴
### 배울 내용 [#배울-내용]
커스텀 서브에이전트, 규칙, MCP 서버를 결합해 실제 개발 시나리오에 적용하는 실용적인 연동 워크플로입니다.
***
## 연동 방법 [#연동-방법]
| 방법 | 가장 적합한 경우 | 설정 |
| ----------------- | ---------------- | --------------------------- |
| **커스텀 서브에이전트** | AI 기반 전문 작업 | `~/.verdent/subagents/*.md` |
| **규칙(AGENTS.md)** | 팀 표준과 동작 방식 | 프로젝트 루트의 `AGENTS.md` |
| **MCP 서버** | 프로토콜을 준수하는 외부 도구 | `.mcp.json`(프로젝트 루트) |
**철학:** 여러 방법을 조합해 필요에 맞는 종합적인 워크플로를 만듭니다.
***
## 일반적인 연동 패턴 [#일반적인-연동-패턴]
### 데이터베이스 개발 워크플로 [#데이터베이스-개발-워크플로]
**스택:** 마이그레이션 리뷰어 서브에이전트 + AGENTS.md 표준 + PostgreSQL MCP 서버
**서브에이전트:**
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```
**AGENTS.md:**
```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```
**MCP:** 쿼리 실행, 스키마 검사, 마이그레이션 검증을 위한 PostgreSQL 서버
**워크플로:** 마이그레이션 작성 → @migration-reviewer가 검증 → MCP이 스테이징에서 테스트 → PR 문서화
***
### 보안을 포함한 API 개발 [#보안을-포함한-api-개발]
**스택:** 보안 감사자 + AGENTS.md 규칙 + 커스텀 API 테스트 도구
**구성 요소:**
* **서브에이전트:** `@api-security-auditor` - 입력 검증, SQL 인젝션, 인증, 속도 제한
* **규칙:** 모든 엔드포인트는 보안 리뷰가 필요하며, 공개 API에는 속도 제한을 적용합니다.
* **외부 도구:** 커스텀 연동을 통한 자동 엔드포인트 테스트와 보안 스캔
**결과:** PR 승인 전에 자동 보안 리뷰가 수행됩니다.
API 테스트 및 보안 스캔 도구는 도구 구성에 따라 커스텀 MCP 서버 구현이나 다른 연동 방법을 통해 연동할 수 있습니다.
***
### 프론트엔드 접근성 [#프론트엔드-접근성]
**스택:** 접근성 감사자 + WCAG 규칙 + Lighthouse 연동
**워크플로:**
```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```
Lighthouse와 기타 접근성 도구는 워크플로에 따라 커스텀 MCP 서버 또는 CI/CD 파이프라인 연동을 통해 연결할 수 있습니다.
***
## MCP 설정 예시 [#mcp-설정-예시]
### MCP 이해하기 [#mcp-이해하기]
\*\*Model Context Protocol(MCP)\*\*은 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 서버는 이 프로토콜을 구현하는 실행 파일입니다. 데이터베이스 연결이나 API 엔드포인트가 아니라, 실행되어 JSON-RPC 2.0으로 통신하는 프로그램입니다.
**핵심 개념:**
* **MCP 서버**: MCP 프로토콜을 구현하는 실행 파일(Node.js 패키지, Python 스크립트 등)
* **설정**: Verdent이 서버를 시작하는 방법을 알려줍니다(`command` + `args`).
* **통신**: 서버는 자체 비즈니스 로직(쿼리, API 호출 등)을 처리합니다.
### 기본 설정 [#기본-설정]
**위치:** 프로젝트 루트의 `.mcp.json`
```json PostgreSQL Server
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
}
}
}
```
```json GitHub Server
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
```json Multiple Servers
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
},
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
**설명:**
* `mcpServers` - MCP 설정에 필요한 최상위 키
* `command` - 실행할 실행 파일(일반적으로 Node.js 패키지에는 `npx` 사용)
* `args` - 명령에 전달되는 인수(패키지 이름, 연결 문자열 등)
* `env` - 인증/설정을 위한 환경 변수
### 다중 환경 [#다중-환경]
```json
{
"mcpServers": {
"postgres-dev": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"${DEV_DATABASE_URL}"
]
},
"postgres-staging": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"${STAGING_DATABASE_URL}"
]
},
"postgres-prod": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"${PROD_DATABASE_URL}"
]
}
}
}
```
**권장 사항:** 자격 증명을 안전하게 유지하려면 연결 문자열에 환경 변수를 사용합니다. MCP 서버는 구현 방식에 따라 내부적으로 읽기 전용 동작을 처리합니다. 접근 제어 옵션은 해당 서버 문서를 확인하세요.
**MCP 더 알아보기:**
* [Model Context Protocol 사양](https://modelcontextprotocol.io/specification)
* [MCP 서버 레지스트리](https://mcp.so/servers) - 사용 가능한 MCP 서버 둘러보기
* [공식 MCP 서버](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem 등
***
## 워크스페이스 연동 [#워크스페이스-연동]
### 프로젝트별 설정 [#프로젝트별-설정]
**설정:**
1. 프로젝트 루트에 저장합니다: `.mcp.json`
2. 팀 공유를 위해 버전 관리에 커밋합니다.
3. 팀원은 프로젝트 MCP 서버를 자동으로 사용합니다.
**마이크로서비스 예시:**
```json
{
"mcpServers": {
"users-db": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/users"
]
},
"orders-db": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5433/orders"
]
}
}
}
```
Kafka 같은 추가 서비스에는 호환되는 MCP 서버 구현이 필요합니다. [mcp.so/servers](https://mcp.so/servers)의 공식 MCP 서버 레지스트리에서 사용 가능한 커뮤니티 서버를 확인할 수 있습니다.
***
## 팀 협업 [#팀-협업]
### 공유 AGENTS.md 표준 [#공유-agentsmd-표준]
팀 전체의 일관성을 위해 버전 관리에 커밋합니다.
```markdown
# AGENTS.md
## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage
## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components
## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```
**장점:** 일관된 동작, 표준 적용, 자동 품질 게이트.
***
## 멀티 에이전트 조정 [#멀티-에이전트-조정]
### 복잡한 기능 워크플로 [#복잡한-기능-워크플로]
**예시:** 새 결제 엔드포인트
```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```
**결과:** 보안 및 데이터베이스 권장 사항이 적용된, 완전히 리뷰된 엔드포인트입니다.
***
## 연동 권장 사항 [#연동-권장-사항]
### 단계적 도입 [#단계적-도입]
**1단계:** 기본 규칙
```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```
**2단계:** 전문 서브에이전트 추가
```markdown
## Code Review
- Run @security-reviewer before PR
```
**3단계:** MCP 연동
```markdown
## Database Access
- Use MCP postgres-staging for queries
```
### 전략적 조합 [#전략적-조합]
| 조합 | 목적 | 예시 |
| ------------ | ------------------------------- | ------------------------------------------- |
| 규칙 + 서브에이전트 | 규칙은 *언제*를 정의하고, 서브에이전트는 *분석*합니다 | AGENTS.md: "Review with @security-reviewer" |
| 규칙 + MCP | 규칙은 *어떤* 서버를 지정하고, MCP는 *접근*합니다 | AGENTS.md: "Use db-staging only" |
| 서브에이전트 + MCP | 서브에이전트가 *외부 데이터*에 MCP를 사용합니다 | 보안 감사자가 API 엔드포인트를 쿼리합니다 |
### 팀 문서화 권장 사항 [#팀-문서화-권장-사항]
팀을 위해 연동을 문서화할 때는 다음을 포함합니다.
* **커스텀 서브에이전트**: 각 서브에이전트의 이름, 목적, 호출해야 하는 시점을 나열합니다.
* **AGENTS.md 규칙**: 각 표준의 “왜”를 설명하는 근거와 함께 규칙을 문서화합니다.
* **MCP 서버**: 각 서버의 목적, 접근 수준(읽기 전용/쓰기), 사용 시점을 설명합니다.
* **연동 워크플로**: 구성 요소가 함께 작동하는 방식을 보여주는 예시 워크플로를 제공합니다.
* **문제 해결**: 현재 설정에 특화된 일반적인 문제와 해결 방법을 문서화합니다.
새 팀원이 설정을 빠르게 이해할 수 있도록 연동 문서를 `.mcp.json` 및 `AGENTS.md` 파일과 함께 커밋하세요.
***
## 문제 해결 [#문제-해결]
**문제:** 예상한 시점에 서브에이전트가 호출되지 않음
**확인:**
**위치**: 파일이 `~/.verdent/subagents/[name].md`에 있는지 확인합니다.
**YAML 프런트매터**: 필수 `name` 및 `description` 필드를 포함한 유효한 문법인지 확인합니다.
**호출 정책**: 사용 방식과 일치하는지 확인합니다(strict는 명시적인 @-mention이 필요함).
**설명**: 에이전트 `description`가 서브에이전트를 사용해야 하는 시점을 정확히 설명하는지 확인합니다.
**재시작**: 서브에이전트 정의를 다시 로드하려면 Verdent을 다시 시작해 봅니다.
***
**일반적인 원인:**
* 서브에이전트 파일 이름 또는 @-mention의 오타
* 프런트매터의 잘못된 YAML 문법
* 서브에이전트 `description`가 작업 컨텍스트와 일치하지 않음
**문제:** AGENTS.md 규칙이 적용되지 않음
**확인:**
**위치**: 파일이 프로젝트 루트 디렉터리에 있는지 확인합니다.
**문법**: 파싱 오류가 없는 유효한 Markdown인지 확인합니다.
**지시 방식**: 구체적인 명령을 사용합니다("Try to..."가 아니라 "Always use...").
**세션**: 새 대화를 시작해 규칙 적용을 새로 테스트합니다.
**충돌**: 사용자 규칙이 프로젝트 규칙을 의도치 않게 재정의하는지 확인합니다.
***
**일반적인 원인:**
* AGENTS.md가 잘못된 디렉터리에 있음(프로젝트 루트여야 함)
* AI가 다르게 해석할 수 있는 모호한 지시
* 규칙은 적용되었지만 결과가 예상과 다름(문구를 다듬으세요)
**문제:** MCP 서버가 시작되거나 연결되지 않음
**확인:**
**문법**: `.mcp.json`에 유효한 JSON이 들어 있는지 확인합니다(검증에는 `jq` 사용).
**구조**: 필수 `mcpServers` 키가 최상위에 있는지 확인합니다.
**서버 설정**: 각 서버에 `command` 및 `args`가 올바르게 지정되어 있는지 확인합니다.
**패키지**: MCP 서버 패키지에 접근할 수 있는지 확인합니다(`npx`는 패키지를 자동으로 다운로드하며, `-y` 플래그는 확인 프롬프트를 건너뜁니다).
**환경**: `env` 객체의 변수가 셸에 올바르게 설정되어 있는지 확인합니다.
**권한**: 서버 실행 파일에 적절한 실행 권한이 있는지 확인합니다.
***
**일반적인 원인:**
* JSON 오타(누락된 쉼표, 닫히지 않은 괄호)
* args 배열의 잘못된 패키지 이름
* 누락되었거나 잘못된 환경 변수
* 네트워크/방화벽이 npx 패키지 설치를 차단함
***
**디버그 단계:**
1. JSON 검증: `cat .mcp.json | jq .`
2. 명령 수동 테스트: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
3. 환경 확인: `echo $GITHUB_TOKEN`
4. 구체적인 오류 메시지를 확인하려면 Verdent 로그를 검토합니다.
***
## 함께 보기 [#함께-보기]
전체 확장 방법 개요
Model Context Protocol 세부 정보