CodeAlive의 코드 이해 플랫폼을 AI 비서에 연결하세요

AI 비서를 CodeAlive의 강력한 코드 이해 플랫폼에 단 몇 초 만에 연결하세요!

이 MCP (Model Context Protocol) 서버는 Claude Code, Cursor, Claude Desktop, Continue, VS Code (GitHub Copilot), Cline, Codex, OpenCode, SourceCraft Code Assistant, SourceCraft CLI, Zed, KodaCode, GigaCode, Qwen Code, Gemini CLI, Roo Code, Goose, Kilo Code, Windsurf, Kiro, Qoder, n8n, Amazon Q Developer와 같은 AI 클라이언트가 CodeAlive의 고급 시맨틱 코드 검색 및 코드베이스 상호 작용 기능에 접근할 수 있도록 합니다.

CodeAlive는 그래프 기반 검색(graph-based retrieval)을 통해 구동되며 MCP를 통해 노출되는 대규모 코드베이스를 위한 Context Engine입니다. 이는 Cursor, Claude Code, Codex와 같은 AI 에이전트가 파일을 맹목적으로 읽도록 강요하는 대신 정확한 리포지토리 컨텍스트를 제공합니다. 저희 RepoQA 벤치마크에서 CodeAlive + Qwen3.6 deep은 약 25배 낮은 모델 비용으로 프론티어 에이전트 수준의 품질에 도달했으며, 시맨틱 검색을 통해 포착된 토큰 수를 45% 줄였습니다.

이는 Context7과 같지만, 사용자의 (대규모) 코드베이스를 위한 것입니다.

이를 통해 AI 코딩 에이전트는 다음을 할 수 있습니다:

시맨틱 검색으로 관련 코드를 더 빠르게 찾기
격리된 파일을 넘어 큰 그림 이해하기
완전한 프로젝트 컨텍스트로 더 나은 답변 제공하기
추측 제거를 통해 비용과 시간 절약하기

연결되면 다음과 같은 강력한 도구에 접근할 수 있습니다:

• 인덱싱된 리포지토리 및 워크스페이스 목록 가져오기get_data_sources

• 인덱싱된 아티팩트 전반의 표준 시맨틱 검색semantic_search

• 파일 내용 내 정확한 리터럴 또는 정규식 텍스트 검색, 그리고 리터럴 파일 이름/경로 일치(내용에 해당 이름이 언급되지 않아도 Form.xml과 같은 파일을 반환), 콘텐츠 일치에 대한 라인별 미리보기 제공 - 선택된 리포지토리에 대한 리포지토리 수준의 개요 가져오기get_repository_ontology

• 하나의 리포지토리에 대해 경계가 지정된 파일 트리 검사하기get_file_tree

• 라인 범위와 함께 선택적으로 리포지토리 상대 파일 경로 읽기read_file

• 관련 검색 결과를 위한 전체 소스 로드 (식별자가 누락되거나 액세스할 수 없는 경우 보고되며, 조용히 제외되지 않음)fetch_artifacts

• 하나의 아티팩트에 대한 호출 그래프, 상속 및 참조 관계 확장get_artifact_relationships

• 지원되는 ArtifactQuery 엔티티, 필드 및 예시 검사get_artifact_query_schema

• 선택된 리포지토리에 걸쳐 읽기 전용 메타데이터 분석 실행query_artifact_metadata

• 상태 비저장(stateless)이며 느린 합성 코드베이스 Q&A; 명시적으로 요청할 때만 호출`chat``

설정 후, AI 비서와 다음 명령들을 시도해 보세요:

"사용 가능한 모든 리포지토리를 보여줘"→ get_data_sources 사용

"유저 서비스에서 인증 코드를 찾아줘"→ semantic_search 사용

"JWT 토큰과 일치하는 정확한 정규식을 찾아줘"→ grep_search 사용

"이 코드베이스에서 결제 흐름이 어떻게 작동하는지 설명해줘"→ 보통 semantic_search로 시작합니다.

/grep_search`

, 그리고 선택적으로 chat

semantic_search

및 grep_search

가 대부분의 에이전트에게 기본 도구가 되어야 합니다. chat는 검색(retrieval)보다 훨씬 오래 걸릴 수 있는 상태 비저장 합성 폴백(fallback)이며, 에이전트가 온톨로지, 검색, 가져오기/읽기, 관계, ArtifactQuery 및 로컬 파일 읽기를 통해 다단계 워크플로우를 실행할 수 있을 때는 보통 불필요합니다. 만약 에이전트가 서브에이전트를 지원한다면, 가장 높은 신뢰도의 경로는 semantic_search와 grep_search를 오케스트레이션(orchestrates)하는 집중된 서브에이전트를 위임하는 것입니다.

더 나은 경험을 위해 CodeAlive Agent Skill을 MCP 서버와 함께 설치하세요. MCP 서버는 에이전트에게 CodeAlive의 도구에 대한 액세스를 제공하며, 이 스킬은 효과적으로 사용하기 위한 최적의 워크플로우와 쿼리 패턴을 가르쳐줍니다.

대부분의 에이전트(Cursor, Copilot, Gemini CLI, Codex 및 30개 이상) — 다음 명령어로 스킬 설치:

npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine

Claude Code — 플러그인(권장)을 설치하세요. 여기에는 스킬과 Claude 전용 향상 기능이 포함되어 있습니다.

플러그인 마켓플레이스에 CodeAlive-AI/codealive-skills 추가
/plugin marketplace add CodeAlive-AI/codealive-skills
/plugin install codealive@codealive-marketplace

• 에이전트 스킬 (Agent Skill)
• 빠른 시작 (원격) (Quick Start (Remote))
• AI 클라이언트 통합 (AI Client Integrations)
• 고급: 로컬 개발 (Advanced: Local Development)
• 커뮤니티 플러그인 (Community Plugins)
• HTTP 배포 (자체 호스팅 및 클라우드) (HTTP Deployment (Self-Hosted & Cloud))
• Windows 및 WSL
• 사용 가능한 도구 (Available Tools)
• 사용 예시 (Usage Examples)
• 문제 해결 (Troubleshooting)
• MCP 레지스트리에 게시하기 (Publishing to MCP Registry)
• 라이선스 (License)

가장 빠르게 시작하는 방법: 설치가 필요 없습니다! https://mcp.codealive.ai/api의 원격 MCP 서버를 이용하면 CodeAlive의 기능을 즉시 사용할 수 있습니다.

• https://app.codealive.ai/에서 가입하세요.
• MCP & API로 이동하여
  **"+ API 키 생성"**을 클릭하고, API 키를 즉시 복사하세요. 이 키는 다시 볼 수 없습니다!

MCP 통합 가이드에서 클라이언트를 선택하고 현재 설정 지침을 따르세요.

AI 에이전트에게 CodeAlive MCP 서버 설치를 요청할 수도 있습니다.

• 다음 프롬프트를 AI 에이전트에 복사하여 붙여넣으세요. API 키는 포함하지 마세요:

Add the CodeAlive MCP server by following the guide for my client at https://docs.codealive.ai/integrations/mcp
Prefer the Remote HTTP option when available. Do not ask me to paste an API key into chat. When the key is needed, ask me to create a CodeAlive API key and copy it to my clipboard. After I confirm, insert it directly from the clipboard into the required secure configuration without displaying, echoing, logging, or exposing it in command arguments, command output, or model context. If you cannot safely use the clipboard without exposing the value, tell me exactly where to paste it myself.

그런 다음 실행을 허용하세요.

• AI 에이전트를 다시 시작하세요.

클라이언트별 설정은 CodeAlive 문서에 유지되므로 파일 경로, 전송 방식 및 인증 지침이 최신 상태로 유지됩니다.

여기에서 시작하세요: MCP 통합 가이드

클라이언트 | 설정 가이드
| :--- |
| Claude Code | Claude Code |
| ... |
미등록 클라이언트의 경우, 다음 일반 연결 세부 정보를 사용하고 이를 해당 클라이언트의 MCP 구성 형식에 맞게 조정하십시오:

엔드포인트(Endpoint): https://mcp.codealive.ai/api

전송 방식(Transport): 스트리밍 가능 HTTP (Streamable HTTP)
인증 헤더(Authentication header): Authorization: Bearer YOUR_API_KEY_HERE

프라이빗 배포의 경우, 엔드포인트를 서버의 /api URL로 대체하십시오. 배포 지침은 Self-Hosting을 참조하십시오.

서버 연결이 설정의 절반입니다. 코딩 에이전트는 프로젝트 지침에서 CodeAlive 사용을 선호하라고 명시하지 않는 한 자체 내장 검색 기능을 계속 사용할 수 있습니다. AGENTS.md, CLAUDE.md 및 클라이언트별 지침 파일에 대한 즉석 규칙은 Instructing Coding Agents를 참조하십시오.

MCP 서버를 사용자 정의하거나 기여하려는 개발자를 위한 내용입니다.

• Python 3.11 이상<br>- uv (권장) 또는 pip

# 저장소 복제하기
git clone https://github.com/CodeAlive-AI/codealive-mcp.git
cd codealive-mcp
...

서버를 로컬에 설치한 후, MCP 클라이언트가 첫 번째 인수로 src/codealive_mcp_server.py를 사용하고 프로세스 환경 변수에 CODEALIVE_API_KEY를 제공하도록 .venv/bin/python을 가리키게 하십시오. 클라이언트별 구성은 MCP 통합 가이드에 포함되어야 합니다.

# 로컬 HTTP 서버 시작하기
export CODEALIVE_API_KEY="your_api_key_here"
python src/codealive_mcp_server.py --transport http --host localhost --port 8000
...

HTTP 전송 방식은 Host 및 브라우저 Origin 헤더를 검증합니다. 루프백 호스트(localhost, 127.0.0.1, ::1)는 추가 구성 없이 작동합니다. 공유된 호스트 이름의 경우, 정확한 허용 목록(allowlist)을 구성하십시오:

export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.codealive.yourcompany.com"
# 브라우저 호출자 전용; 일반 MCP 클라이언트는 Origin을 보내지 않습니다.
export CODEALIVE_MCP_ALLOWED_ORIGINS="https://mcp.codealive.yourcompany.com"
...

동등한 반복 가능한 CLI 옵션은 --allowed-host 및 --allowed-origin입니다. 인터넷에 노출되는 서버의 경우 *를 사용하지 마십시오.

변경 사항을 적용한 후, 모든 것이 제대로 작동하는지 빠르게 확인하세요:

# pyproject.toml과 정확히 일치하도록 매칭합니다. 이전 버전의 uv는 잠긴(locked) 설정을 거부합니다.
uv --version # 예상값: uv 0.11.28
uv sync --locked --extra test
...

스모크 테스트(smoke test)를 통해 다음 사항을 확인합니다:

• 서버가 시작되고 올바르게 연결되는지
• 모든 도구가 등록되었는지
• 각 도구가 적절하게 응답하는지
• 매개변수 유효성 검사가 작동하는지
• 약 5초 이내에 실행되는지

MCP 서버를 HTTP 서비스로 배포하여 팀 전체에서 접근하거나 자체 호스팅(self-hosted) CodeAlive 인스턴스와 통합할 수 있습니다.

CodeAlive MCP 서버는 Docker를 사용하여 HTTP 서비스로 배포할 수 있습니다. 이를 통해 여러 AI 클라이언트가 단일 공유 인스턴스에 연결할 수 있으며, 자체 호스팅된 CodeAlive 배포와 통합하는 것이 가능합니다.

예시를 기반으로 docker-compose.yml 파일을 생성하세요:

# 예제 다운로드
curl -O https://raw.githubusercontent.com/CodeAlive-AI/codealive-mcp/main/docker-compose.example.yml
mv docker-compose.example.yml docker-compose.yml
...

설정 옵션:

• CodeAlive Cloud (기본값): CODEALIVE_BASE_URL 환경 변수를 제거합니다(기본값 https://app.codealive.ai 사용).

  • OAuth 지원이 필요한 원격 클라이언트의 경우, https://mcp.codealive.ai/api만 구성하고 프롬프트가 나타나면 브라우저를 통해 로그인 절차를 완료하세요.
  • 기존 API 키 클라이언트는 여전히 Authorization: Bearer YOUR_KEY를 통해 지원됩니다.

• 자체 호스팅 CodeAlive: CODEALIVE_BASE_URL을 사용자의 CodeAlive 인스턴스 URL(예: https://codealive.yourcompany.com)로 설정합니다.

  • CODEALIVE_MCP_ALLOWED_HOSTS를 이 MCP 서버에 클라이언트가 사용하는 정확한 호스트 이름으로 설정해야 합니다. 클라이언트는 반드시 Authorization: Bearer YOUR_KEY 헤더를 통해 API 키를 제공해야 합니다.

• 전체 구성 템플릿은 docker-compose.example.yml을 참조하세요.

예를 들어, 현재 Codex 및 Claude Code 클라이언트는 CodeAlive API 키를 저장하지 않고도 브라우저 OAuth를 사용할 수 있습니다.

Cursor와 OpenCode 역시 동일한 URL에서 OAuth를 자동으로 발견합니다. UI가 자동으로 프롬프트하지 않을 경우 cursor-agent mcp login codealive 또는 opencode mcp auth codealive를 사용하세요. API 키 설정은 호환성 옵션으로 계속 사용할 수 있습니다.

원격 HTTP 배포는 레거시 API 키 클라이언트가 롤아웃되는 동안 브라우저 인증을 활성화할 수 있게 합니다. OAuth 모드는 MCP 보호 리소스 메타데이터(MCP Protected Resource Metadata)를 게시하고, 정확한 발급자/리소스 바운드 JWT(JWT)를 검증하며, 이를 별도의 단기 Tool API 토큰으로 교환합니다. 들어오는 MCP 베어러 토큰은 다운스트림으로 절대 전달되지 않습니다.

권한 부여 서버(authorization server)와 MCP 서비스 값은 정확히 일치해야 합니다. CodeAlive Web.Server에서는 해당 설정들이 McpOAuth 아래에 존재합니다 (Enabled, Issuer, Resource, ToolApiResource, InternalClientId, 및 InternalClientSecret). 복제본 간 및 재시작 시 Web.Server 데이터 보호 키 링(Data Protection key ring)과 OpenIddict 서명/암호화 인증서(signing/encryption certificates)를 유지하세요. 다운타임 없는 내부 자격 증명 로테이션을 위해서는 새 자격 증명에 새로운 클라이언트 ID를 부여하고, 현재 및 PreviousInternalClientId/PreviousInternalClientSecret와 함께 Web.Server를 배포하세요.

, roll
MCP 복제본을 새로운 현재 쌍에 연결한 다음 이전 쌍을 제거합니다. Web.Server는 기존 클라이언트 ID 하에서 비밀 정보를 제자리에서 변경하는 대신 의도적으로 시작 실패를 일으킵니다.
Web.Server와 MCP 플래그를 같은 롤아웃(rollout)에서 활성화해야 합니다. 절반만 활성화된 배포는 유효한 안정 상태가 아닙니다. API 키 자격 증명은 명시적인 레거시 문법을 유지하며, OAuth 검증 실패 후 폴백(fallback)으로 절대 사용되지 않습니다.

CodeAlive Cloud와 동일한 일반 연결 세부 정보를 사용하되, 엔드포인트를 배포의 /api로 대체하세요.

URL:

엔드포인트: https://your-server.example.com/api

전송 방식: 스트림 가능한 HTTP (Streamable HTTP)
인증 헤더: Authorization: Bearer YOUR_API_KEY_HERE

정확한 구성 형식은 관련 클라이언트 통합 가이드를 여세요.

Windows 및 WSL 설정에 대한 클라이언트별 문서는 다음을 사용하세요:

WSL2에서 실행되는 자체 호스팅 서버의 경우, Windows 클라이언트는 서버의 /api에 도달할 수 있어야 합니다.