AI 어시스턴트가 개발자의 작업 방식을 바꾸고 있지만, 여러분의 아키텍처 문서는 볼 수 없습니다. MCP 서버가 이 격차를 메웁니다. 이 가이드는 MCP의 정의, 아키텍처에 왜 중요한지, 그리고 Archyl의 56개 MCP 도구로 Claude나 Cursor에서 직접 아키텍처를 쿼리, 생성, 검증하는 방법을 다룹니다.

아키텍처 문서화를 위한 MCP 서버 활용법

AI 코딩 어시스턴트는 이제 필수가 되었습니다. Claude Code는 복잡한 시스템 리팩토링을 돕습니다. Cursor는 기능 개발을 가속합니다. GitHub Copilot은 구현을 제안합니다. 하지만 이 모든 도구에는 공통된 사각지대가 있습니다: 여러분의 아키텍처를 모릅니다.

"User Service에 새 엔드포인트를 추가해줘"라고 AI 어시스턴트에게 요청하면, User Service가 Auth Service와 gRPC로 통신하고, PostgreSQL에 데이터를 저장하고, Kafka에 이벤트를 발행하며, ADR에 문서화된 특정 보안 요구사항이 있다는 것을 모릅니다. AI가 추측하고, 여러분이 수정하면, 생산성 향상의 절반이 사라집니다.

MCP 서버가 이 문제를 해결합니다. AI 어시스턴트에게 아키텍처 문서에 대한 구조화된 접근을 제공하여, 시스템 설계를 쿼리 가능하고 실행 가능한 데이터 소스로 바꿉니다. 이 가이드는 아키텍처 문서화를 위한 MCP 서버 활용에 대해 알아야 할 모든 것을 다룹니다 -- MCP의 정의, 중요성, Archyl과의 설정 방법.

MCP (Model Context Protocol)란?

MCP -- Model Context Protocol -- 는 Anthropic이 만든 개방형 표준으로, AI 어시스턴트를 외부 도구 및 데이터 소스에 연결합니다. AI 모델이 외부 기능을 발견하고, 호출하고, 결과를 받는 구조화된 방법을 정의합니다.

MCP를 범용 어댑터로 생각하세요. MCP 이전에는 모든 AI 어시스턴트가 외부 도구와 통합하는 고유한 독점 방식을 가지고 있었습니다. MCP는 이를 표준화하여 다른 AI 어시스턴트에서 작동하는 단일 프로토콜을 만듭니다.

MCP 서버는 MCP 프로토콜을 통해 도구 세트를 노출하는 서비스입니다. 각 도구에는 이름, 설명, 입력 매개변수, 출력 형식이 있습니다. AI 어시스턴트가 MCP 서버에 연결하면, 사용 가능한 도구를 발견하고 대화 중에 필요에 따라 호출할 수 있습니다.

아키텍처 문서의 경우, 이는 아키텍처 모델이 MCP 호환 AI 어시스턴트가 사용할 수 있는 쿼리 가능하고 수정 가능한 도구 세트가 된다는 것을 의미합니다. AI가 파일을 파싱하거나 시스템 구조를 추측할 필요 없이 -- 권위 있는 소스 오브 트루스를 직접 쿼리할 수 있습니다.

아키텍처에 MCP가 필요한 이유

아키텍처 문서는 MCP가 완벽하게 해결하는 여러 요구의 교차점에 위치합니다.

AI 지원 개발에서 맥락이 전부

AI 생성 코드의 품질은 AI가 가진 맥락의 품질에 정비례합니다. AI 어시스턴트가 여러분의 아키텍처를 이해할 때 -- 어떤 서비스가 존재하고, 어떻게 통신하고, 어떤 기술을 사용하고, 어떤 제약이 적용되는지 -- 시스템에 자연스럽게 맞는 코드를 생성합니다.

아키텍처 맥락 없이, AI 어시스턴트는 추정합니다. 서비스가 gRPC를 사용하는데 REST API를 제안할 수 있습니다. 아키텍처가 서비스 레이어를 통하도록 요구하는데 직접 데이터베이스 연결을 만들 수 있습니다. 시스템이 event-driven 통신을 사용하는데 동기 호출을 제안할 수 있습니다.

MCP가 AI 어시스턴트에게 실제 아키텍처에 대한 접근을 제공하여 이러한 불일치를 제거합니다.

아키텍처 문서는 구조화된 데이터

자유 형식 문서(위키, Confluence 페이지, README 파일)와 달리, C4 프레임워크로 모델링된 아키텍처 문서는 본질적으로 구조화되어 있습니다. 시스템은 컨테이너를 포함합니다. 컨테이너는 컴포넌트를 포함합니다. 요소에는 기술, 설명, 관계가 있습니다. ADR에는 상태와 영향받는 요소가 있습니다.

이 구조는 MCP 도구에 자연스럽게 매핑됩니다. 각 아키텍처 요소 유형은 쿼리 가능한 엔티티가 됩니다. 각 작업(목록, 조회, 생성, 업데이트)은 도구가 됩니다. AI 어시스턴트가 개발자가 파일 시스템을 탐색하듯 아키텍처 모델을 탐색할 수 있습니다.

문서는 양방향이어야 함

대부분의 문서 도구는 API 관점에서 읽기 전용입니다. 문서를 볼 수는 있지만, 수정하려면 특정 애플리케이션을 열어야 합니다. MCP는 양방향 상호작용을 가능하게 합니다: AI 어시스턴트가 아키텍처 모델에서 읽기도 하고 쓰기도 할 수 있습니다.

이는 AI 어시스턴트가 아키텍처를 쿼리할 뿐만 아니라 수정을 제안할 수도 있다는 뜻입니다 -- 새 컴포넌트 추가, 관계 생성, ADR 초안 작성. 개발자가 이러한 변경을 검토하고 승인하지만, AI가 문서 업데이트의 기계적 작업을 수행합니다.

Archyl의 MCP 서버: 아키텍처를 위한 56개 도구

Archyl은 아키텍처 문서화를 위한 가장 포괄적인 MCP 서버 구현 중 하나를 제공합니다. 아키텍처 모델링의 전체 범위에 걸쳐 56개 도구가 조직되어 있으며, C4 모델 쿼리부터 릴리스 관리와 드리프트 추적까지 모든 것을 다룹니다.

도구 카테고리의 개요입니다.

C4 모델 쿼리

핵심 쿼리 도구로 AI 어시스턴트가 모든 레벨에서 아키텍처를 탐색할 수 있습니다:

list_systems / get_project_c4_model -- 프로젝트의 모든 소프트웨어 시스템 발견
list_containers / list_components -- C4 계층 구조 탐색
list_relationships -- 요소 간 연결 방식 이해
get_element_technologies -- 모든 요소의 기술 스택 확인
get_element_owners -- 누가 무엇을 소유하는지 파악

이 도구들은 아키텍처에 대한 자연어 쿼리를 가능하게 합니다. "Order Service는 어떤 데이터베이스에 의존하나요?"라고 물으면, AI가 Order Service의 관계를 나열하고, 데이터베이스 컨테이너를 필터링하여, 정확한 답을 반환할 수 있습니다.

아키텍처 요소 관리

쓰기 도구로 AI 어시스턴트가 아키텍처 모델을 수정할 수 있습니다:

create_system / update_system / delete_system -- 소프트웨어 시스템 관리
create_container / update_container / delete_container -- 컨테이너 관리
create_component / update_component / delete_component -- 컴포넌트 관리
create_relationship / update_relationship / delete_relationship -- 연결 관리

이 도구들은 개발 중 문서를 최신으로 유지하는 데 특히 강력합니다. 코드베이스에 새 서비스를 추가할 때, AI 어시스턴트에게 아키텍처 모델에 해당 컨테이너를 추가하고, 기술을 설정하고, 적절한 관계를 만들도록 요청할 수 있습니다 -- 모두 IDE를 떠나지 않고.

Architecture Decision Records

ADR 도구가 의사결정 문서를 AI 워크플로에 가져옵니다:

list_adrs / get_adr -- 기존 결정 쿼리
create_adr / update_adr -- 새 ADR 생성 또는 기존 것 업데이트
link_adr_to_element -- 결정을 영향받는 요소에 연결

AI 어시스턴트와 기술 선택을 논의할 때, 관련 결정에 대한 기존 ADR을 확인하고, 현재 결정에 대한 새 ADR 초안을 작성하고, 관련 아키텍처 요소에 연결할 수 있습니다.

API 계약 및 이벤트 채널

통합 문서 도구가 서비스 경계를 다룹니다:

list_api_contracts / create_api_contract -- API 명세서 관리
list_event_channels / create_event_channel -- 비동기 통신 모델링
link_api_contract / link_event_channel -- 명세서를 요소에 연결

이 도구들은 아키텍처와 구현 사이의 연결을 유지하는 데 도움이 됩니다. 새 API 엔드포인트를 만들 때, AI가 해당 서비스에 API 계약이 존재하는지 확인하고 업데이트를 제안할 수 있습니다.

문서 및 협업

더 넓은 문서 도구가 팀 워크플로를 지원합니다:

create_documentation / update_documentation -- 프로젝트 문서 관리
create_comment / list_comments -- 아키텍처 요소에 주석 달기
list_flows / create_flow -- 사용자 및 시스템 플로우 문서화
get_drift_score / compute_drift_score -- 문서 정확도 확인

릴리스 및 메트릭

운영 도구가 아키텍처를 딜리버리에 연결합니다:

create_release / list_releases -- 배포 추적
get_dora_metrics / get_dora_trend -- 엔지니어링 성과 측정
list_environments -- 배포 대상 파악

실제 예시: MCP 실전 활용

개발자가 일상 워크플로에서 Archyl의 MCP 서버를 사용하는 구체적인 예시입니다.

예시 1: Claude Code에서 시스템 쿼리

Claude Code에서 작업 중이고 변경하기 전에 아키텍처를 이해해야 합니다:

사용자: 프로젝트에 어떤 시스템과 컨테이너가 있나요?

Claude: 아키텍처를 확인해보겠습니다.
[list_systems 호출, 각 시스템에 대해 list_containers 호출]

프로젝트 "E-Commerce Platform"에는 3개의 시스템이 있습니다:
1. E-Commerce Platform (software_system)
   - API Gateway (Go, Kong)
   - User Service (Go, PostgreSQL)
   - Order Service (Java, PostgreSQL)
   - Product Service (Node.js, MongoDB)
   - Notification Service (Python, Redis)
   - Event Bus (Kafka)

2. Stripe (external_system)
   - 결제 처리 게이트웨이

3. SendGrid (external_system)
   - 트랜잭션 이메일 서비스

AI가 환각이 아닌 문서화된 아키텍처의 실제 데이터를 반환합니다.

예시 2: Cursor에서 컴포넌트 생성

서비스에 새 모듈을 추가하고 문서화하려 합니다:

사용자: API Gateway에 RateLimiter 컴포넌트를 추가했어요.
     Redis와 golang.org/x/time/rate 라이브러리를 사용합니다.
     아키텍처에 추가해줄 수 있나요?

Cursor: C4 모델에 추가하겠습니다.
[create_component 호출 - name="RateLimiter",
 container="API Gateway", technologies=["Redis", "Go"]]
[create_relationship 호출 - RateLimiter에서
 Redis 컨테이너로]

완료했습니다. API Gateway에 RateLimiter 컴포넌트를 추가하고
Redis 컨테이너와의 관계를 생성했습니다.

IDE를 떠나지 않고 몇 초 만에 문서가 업데이트됩니다.

예시 3: 리팩토링 전 드리프트 확인

대규모 리팩토링 전에 문서가 얼마나 정확한지 알고 싶습니다:

사용자: 현재 드리프트 점수는 어떤가요? 문서화되지 않은
     서비스가 있나요?

Claude: 확인해보겠습니다.
[get_drift_score 호출]
[get_drift_details 호출]

드리프트 점수는 78/100 (양호)입니다.

감지된 문제:
- Search Service가 프로덕션에서 실행되고 있지만
  C4 모델에 문서화되지 않았습니다
- Analytics Service에 Data Warehouse와의
  문서화되지 않은 관계 2개가 있습니다
- API Gateway의 기술 목록에 "Redis"가
  누락되었습니다 (최근 Rate Limiting에 추가됨)

이 문제들을 수정할까요?

AI가 정확히 무엇이 구식인지 식별하고 자동으로 수정할 수 있습니다.

예시 4: ADR 초안 작성

내부 서비스 통신을 REST에서 gRPC로 전환하는 설계 논의 중:

사용자: 내부 서비스 통신을 REST에서 gRPC로 전환하는 것을
     검토 중입니다. ADR 초안을 작성하고 관련 기존
     결정이 있는지 확인해줄 수 있나요?

Claude: 먼저 기존 ADR을 확인하겠습니다.
[list_adrs 호출]

관련 ADR 1개를 찾았습니다:
- ADR-007: "모든 내부 API에 REST 사용" (Status: Accepted)
  18개월 전에 결정되었습니다.

이를 대체하는 새 ADR을 초안 작성하겠습니다.
[create_adr 호출 - title="내부 통신을
 REST에서 gRPC로 마이그레이션"]

ADR-015가 생성되었습니다:
- Context: 현재 REST 기반 통신이 직렬화
  오버헤드를 추가...
- Decision: 모든 새로운 내부 서비스 통신에
  Protocol Buffers와 함께 gRPC 도입...
- Status: Proposed
- Supersedes: ADR-007

영향받는 서비스에 연결할까요?

AI가 관련 결정을 확인하고, 새 ADR을 초안 작성하고, 관련 아키텍처 요소에 연결하는 것을 제안합니다.

예시 5: 변경 전 영향 이해

서비스 수정 전에 영향 범위를 이해하고 싶습니다:

사용자: Order Service의 데이터베이스 스키마를 변경해야 합니다.
     Order Service에 의존하는 다른 것은 무엇인가요?

Claude: 의존성을 추적해보겠습니다.
[list_relationships 호출 - Order Service 필터]
[get_element_owners 호출 - 의존 요소에 대해]

Order Service에는 다음 의존 항목이 있습니다:
- API Gateway -> Order Service (REST, 주문 관리)
- Order Service -> Payment Service (gRPC, 결제 처리)
- Order Service -> Event Bus (OrderCreated,
  OrderUpdated, OrderCancelled 이벤트 발행)
- Notification Service가 Event Bus에서 주문 이벤트 소비
- Analytics Service가 Event Bus에서 주문 이벤트 소비

소유자:
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team

스키마 변경은 Payment Service(직접 의존)와
주문 이벤트의 모든 소비자에 영향을 줄 수 있습니다.
Payments Team과 Data Team에 조율을 권장합니다.

Archyl의 MCP 서버 설정

Archyl의 MCP 서버 설정은 몇 분이면 됩니다. 가장 일반적인 AI 어시스턴트에 대한 설정 방법입니다.

Claude Code 설정

Claude Code 설정에 Archyl MCP 서버를 추가합니다:

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

설정이 완료되면, Claude Code가 자동으로 56개 도구를 모두 발견하고 모든 대화에서 사용할 수 있습니다.

Cursor 설정

Cursor는 설정에서 MCP 서버를 지원합니다. MCP 섹션에 Archyl을 추가합니다:

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

설정을 추가한 후 Cursor를 재시작합니다. Archyl 도구가 MCP 도구 목록에 나타나며, Cursor가 코드 생성 및 리팩토링 중에 사용할 수 있습니다.

기타 MCP 호환 도구 설정

MCP 프로토콜을 지원하는 모든 도구가 Archyl의 MCP 서버에 연결할 수 있습니다. 서버가 도구 발견이 있는 표준 MCP 엔드포인트를 노출하므로, 호환 클라이언트가 자동으로 사용 가능한 도구를 감지하고 나열합니다.

API 키 생성

Archyl 대시보드에서 MCP API 키를 생성합니다:

조직 설정으로 이동
API 섹션으로 이동
적절한 권한으로 새 API 키 생성
키를 MCP 서버 설정에 복사

다른 용도(예: Claude Code용 하나, CI/CD용 하나)에 대해 별도의 API 키를 만들어 독립적으로 로테이션할 수 있도록 하는 것을 권장합니다.

MCP 기반 아키텍처 문서화 모범 사례

읽기 전용으로 시작

MCP 서버를 처음 설정할 때는 읽기 전용 쿼리로 시작합니다. AI 어시스턴트의 아키텍처 탐색 능력에 익숙해진 후 쓰기 작업을 활성화합니다. 이렇게 하면 도구의 정확성과 신뢰성에 대한 확신을 쌓습니다.

AI 생성 변경 검토

AI 어시스턴트가 아키텍처 요소를 생성하거나 수정할 때, 최종으로 간주하기 전에 변경을 검토합니다. Archyl의 히스토리 및 버전 기능으로 무엇이 변경되었는지 보고 필요시 롤백할 수 있습니다. AI는 강력한 어시스턴트이지만, 아키텍처 결정은 항상 인간의 감독이 있어야 합니다.

MCP와 Architecture as Code 결합

MCP와 architecture as code는 상호 보완적입니다. MCP는 개발 중 인터랙티브 쿼리와 빠른 업데이트에 사용합니다. Architecture as code(archyl.yaml 파일)는 코드 리뷰를 거치는 권위 있고 버전 관리되는 정의에 사용합니다. 두 접근 방식이 서로를 강화합니다.

코드 리뷰에서 MCP 활용

코드 리뷰 중에 AI 어시스턴트에게 코드 변경이 문서화된 아키텍처와 일치하는지 확인하도록 요청합니다. "이 새 API 엔드포인트가 이 서비스에 대해 문서화된 API 계약과 일치하나요?" 또는 "이 데이터베이스 쿼리가 문서화된 대로 서비스 레이어를 통하고 있나요?" AI가 실시간으로 아키텍처 모델에 대해 코드를 검증할 수 있습니다.

팀에 사용 가능한 도구 교육

MCP 도입의 가장 큰 장벽은 인식입니다. 대부분의 개발자는 AI가 아키텍처에 대해 어떤 질문에 답할 수 있는지 모릅니다. 예시를 공유하고, 유용한 쿼리 치트 시트를 만들고, 팀 미팅에서 MCP 워크플로를 시연하세요.

AI 기반 아키텍처 문서화의 미래

MCP 서버는 팀이 아키텍처 문서와 상호작용하는 방식의 근본적인 전환을 나타냅니다. 개발자가 읽는(또는 더 자주, 읽지 않는) 수동적 산출물이 아니라, 개발 워크플로의 적극적인 참여자가 됩니다.

AI 어시스턴트가 코드를 생성하기 전에 아키텍처를 쿼리하고, 변경 후 적합성을 확인하고, 시스템이 발전하면서 문서를 업데이트할 수 있으면, "시스템 작업"과 "시스템 문서화" 사이의 장벽이 사라집니다.

아키텍처 문서가 별도로 유지하는 것이 아니라, 모든 개발 상호작용에 녹아드는 것이 됩니다. AI에게 물어보는 모든 질문, 만드는 모든 코드 변경, 하는 모든 설계 논의 -- 이 모든 것이 아키텍처 모델에 의해 정보를 받고 아키텍처 모델에 반영될 수 있습니다.

이것이 Archyl이 구축하고 있는 미래입니다. MCP 서버는 AI 기반 개발과 구조화된 아키텍처 문서 사이의 다리입니다. 그리고 아키텍처 모델링의 전체 범위를 다루는 56개 도구로, 팀이 필요로 하는 모든 워크플로를 지원할 만큼 포괄적입니다.

Archyl의 MCP 서버로 시작하기로 AI 어시스턴트에게 지금까지 부족했던 아키텍처 맥락을 제공하세요.

아키텍처 문서화를 위한 MCP 서버 활용법 - Archyl Blog