Claude, Cursor, VS Code와 같은 AI 어시스턴트를 아키텍처 문서에 연결하세요

MCP 서버

Archyl은 AI 어시스턴트가 아키텍처 문서와 상호작용할 수 있도록 Model Context Protocol (MCP) 서버를 제공합니다. 이를 통해 강력한 AI 기반 아키텍처 탐색 및 문서화가 가능합니다.

MCP란 무엇인가요?

Model Context Protocol (MCP)은 AI 어시스턴트가 외부 도구와 데이터 소스에 안전하게 접근할 수 있도록 하는 개방형 프로토콜입니다. Archyl의 MCP 서버를 사용하면 AI 어시스턴트가 다음을 수행할 수 있습니다:

프로젝트 목록 조회 및 탐색
아키텍처 요소 생성 및 수정
문서 생성
아키텍처에 대한 질문 답변

지원 도구

Archyl의 MCP 서버는 다음과 호환됩니다:

Antigravity - Google의 AI 기반 IDE
Claude Code - Anthropic의 CLI 도구
Claude Desktop - Claude 데스크톱 애플리케이션
Cursor - AI 우선 코드 에디터
OpenAI Codex - OpenAI의 AI 코딩 어시스턴트
VS Code - GitHub Copilot Chat 연동
Warp - AI 통합 모던 터미널
Windsurf - Codeium의 AI 기반 IDE

인증

MCP 서버는 인증을 위해 API 키가 필요합니다. 사용하는 도구에 따라:

헤더 지원 도구 (Claude Code, Cursor, Warp, Windsurf, Antigravity): X-API-Key 헤더 사용
헤더 미지원 도구 (Claude Desktop, VS Code, OpenAI Codex): URL에 ?apiKey=YOUR_API_KEY 쿼리 파라미터 사용

프로필 → API 키 페이지에서 API 키를 생성하세요.

설정

Antigravity

Antigravity를 열고 Agent 패널에서 "..." 메뉴를 클릭합니다
"MCP Servers" > "Manage MCP Servers" > "View raw config"를 선택합니다
~/.gemini/antigravity/mcp_config.json에 추가합니다:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

변경사항을 적용하려면 Antigravity를 재시작합니다

참고: Antigravity는 HTTP 기반 MCP 서버에 url 대신 serverUrl을 사용합니다.

Claude Code

프로젝트 루트에 .mcp.json 파일을 생성합니다:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Claude Code를 실행하면 MCP 서버가 자동으로 감지됩니다.

Claude Desktop

Claude Desktop 설정을 엽니다
개발자 → MCP 서버로 이동합니다
"서버 추가"를 클릭하고 추가합니다:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"
    }
  }
}

Claude Desktop을 재시작합니다

참고: Claude Desktop 원격 커넥터는 사용자 정의 헤더를 지원하지 않으므로 API 키를 URL 쿼리 파라미터로 전달해야 합니다.

Cursor

프로젝트에 .cursor/mcp.json 파일을 생성합니다:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

MCP 서버를 로드하려면 Cursor를 재시작합니다.

OpenAI Codex

~/.codex/config.toml을 열거나 생성하고 추가합니다:

[mcp_servers.archyl]
url = "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"

변경사항을 적용하려면 Codex CLI 또는 IDE를 재시작합니다.

VS Code

VS Code 설정을 엽니다 (Cmd/Ctrl + ,)
"MCP"를 검색하고 "settings.json에서 편집"을 클릭합니다
추가합니다:

{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"
      }
    }
  }
}

Warp

Warp를 열고 설정 > MCP 서버로 이동합니다
"서버 추가"를 클릭하고 설정을 붙여넣습니다:

{
  "archyl": {
    "url": "https://api.archyl.com/mcp",
    "headers": {
      "X-API-Key": "YOUR_API_KEY"
    }
  }
}

변경사항을 적용하려면 Warp를 재시작합니다

Windsurf

~/.codeium/windsurf/mcp_config.json에서 MCP 설정 파일을 엽니다:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

변경사항을 적용하려면 Windsurf를 재시작합니다.

사용 가능한 도구

연결되면 AI 어시스턴트가 다음 도구를 사용할 수 있습니다:

프로젝트 관리

도구	설명
`list_projects`	모든 프로젝트 목록 조회
`get_project`	프로젝트 상세 정보 조회
`create_project`	새 프로젝트 생성

아키텍처 요소

도구	설명
`list_systems`	프로젝트 내 시스템 목록 조회
`create_system`	새 시스템 생성
`list_containers`	시스템 내 컨테이너 목록 조회
`create_container`	새 컨테이너 생성
`list_components`	컨테이너 내 컴포넌트 목록 조회
`create_component`	새 컴포넌트 생성

관계

도구	설명
`list_relationships`	관계 목록 조회
`create_relationship`	관계 생성

문서

도구	설명
`list_adrs`	아키텍처 결정 기록 목록 조회
`create_adr`	새 ADR 생성
`list_docs`	문서 목록 조회
`create_doc`	문서 생성

대화 예시

아키텍처 탐색

사용자: "전자상거래 프로젝트에 어떤 시스템이 있나요?"

AI: list_systems 도구 사용 "전자상거래 프로젝트에는 4개의 시스템이 있습니다: Web Store, Payment Service, Inventory System, Notification Service..."

요소 생성

사용자: "Web Store 시스템에 세션 저장용 Redis Cache라는 새 컨테이너를 추가해주세요"

AI: create_container 도구 사용 "Web Store 시스템에 '인메모리 세션 저장 캐시'라는 설명과 함께 Redis Cache 컨테이너를 생성했습니다."

문서화

사용자: "PostgreSQL을 MongoDB 대신 선택한 결정에 대한 ADR을 작성해주세요"

AI: create_adr 도구 사용 "ADR-001: 데이터베이스 기술 선택을 생성했습니다. ACID 준수와 쿼리 유연성을 이유로 PostgreSQL을 선택한 결정을 문서화했습니다..."

엔드포인트

Streamable HTTP (MCP)

https://api.archyl.com/mcp

이 엔드포인트를 사용하여 AI 어시스턴트를 Archyl의 아키텍처 문서에 연결하세요. Streamable HTTP 전송 프로토콜을 지원합니다.

문제 해결

연결 실패

API 키가 유효한지 확인하세요
엔드포인트 URL이 올바른지 확인하세요
네트워크 연결을 확인하세요

인증 실패

헤더 지원 도구: X-API-Key 헤더가 올바르게 설정되었는지 확인하세요
헤더 미지원 도구: URL에 ?apiKey= 쿼리 파라미터가 있는지 확인하세요
API 키가 만료되지 않았는지 확인하세요

도구를 찾을 수 없음

올바른 도구 이름을 사용하고 있는지 확인하세요
API 키에 필요한 권한이 있는지 확인하세요

Antigravity 관련 문제

설정에 url이 아닌 serverUrl을 사용하고 있는지 확인하세요
설정 위치는 ~/.gemini/antigravity/mcp_config.json입니다

OpenAI Codex 관련 문제

~/.codex/config.toml의 TOML 구문이 올바른지 확인하세요
테이블 이름으로 [mcp_servers.archyl]을 사용하세요

Warp 관련 문제

설정 > MCP 서버에서 설정을 관리하세요
설정 변경 후 Warp를 재시작하세요

모범 사례

구체적으로 요청하세요

AI에게 아키텍처 수정을 요청할 때는 구체적으로 하세요:

프로젝트 이름을 포함하세요
요소 유형을 지정하세요
설명을 제공하세요

변경사항 검토

AI가 생성한 요소를 항상 검토하세요:

이름과 설명이 정확한지 확인하세요
관계가 올바른지 확인하세요
필요에 따라 업데이트하세요

탐색에 활용하세요

MCP는 다음에 유용합니다:

대규모 아키텍처를 빠르게 탐색
초기 문서 생성
시스템에 대한 질문 답변

MCP 서버 - Archyl Docs