Beyond Entity MCP 사용 가이드

Beyond Entity MCP로 할 수 있는 일

Beyond Entity MCP는 AI 도구가 Beyond Entity 프로젝트의 데이터 모델, 엔터티, 속성, 관계, 프로세서, 데이터 흐름, 변경 이력을 직접 읽고 수정할 수 있게 해 주는 연결 방식입니다.

사용자는 Claude, ChatGPT, Cursor, VSCode 같은 MCP 지원 AI 도구에서 자연어로 요청할 수 있습니다. AI는 Beyond Entity MCP를 통해 프로젝트 구조를 확인하고, 필요한 모델링 작업을 수행하고, 변경 내용을 비교하거나 정리할 수 있습니다.

예를 들어 다음과 같은 일을 맡길 수 있습니다.

기존 데이터베이스 스키마를 분석해 엔터티와 관계를 설명하기
새 테이블, 컬럼, 제약조건, 관계를 설계하거나 추가하기
API, 배치, ETL, 데이터 동기화 같은 프로세서를 모델링하기
SQL이나 처리 로직을 기반으로 데이터 흐름과 변환 관계를 문서화하기
특정 개인정보, 민감정보, 암호화 대상 컬럼을 찾기
브랜치나 커밋 사이에서 모델 변경 사항을 비교하기
웹앱에서 만든 모델을 AI 코드 생성, 리뷰, 문서화 작업에 활용하기
Beyond Entity에 정의된 스키마를 바탕으로 SQL, DDL, 마이그레이션 초안을 생성하기
기존 코드에서 데이터 모델, API, 배치 처리 설계서를 추출하기
현재 코드가 Beyond Entity에 정의된 설계를 따르고 있는지 비교 검토하기

MCP란 무엇인가요?

MCP(Model Context Protocol)는 AI 도구가 외부 시스템의 데이터를 안전하게 읽고 작업을 실행할 수 있도록 해 주는 표준 연결 방식입니다.

일반적인 AI 채팅은 사용자가 복사해서 붙여 넣은 정보만 볼 수 있습니다. Beyond Entity MCP를 연결하면 AI가 사용자의 권한 안에서 Beyond Entity 프로젝트를 직접 조회할 수 있습니다. 따라서 AI는 최신 모델 구조, 속성 정의, 관계, 프로세서, 데이터 흐름, 변경 이력을 기준으로 답변하고 작업할 수 있습니다.

이런 사용자에게 적합합니다

Beyond Entity MCP는 다음과 같은 사용자에게 유용합니다.

데이터 모델러: ERD, 테이블, 컬럼, 키, 관계를 빠르게 설계하고 검토하고 싶은 사용자
백엔드 개발자: 데이터 모델을 기준으로 API, DTO, ORM 엔티티, 마이그레이션 초안을 만들고 싶은 사용자
데이터 엔지니어: ETL, ELT, 배치, 스트리밍, 데이터 동기화 흐름을 모델링하고 문서화하고 싶은 사용자
보안 및 거버넌스 담당자: 개인정보, 민감정보, 암호화 대상, 데이터 계보를 탐색하고 싶은 사용자
프로젝트 리더: 브랜치, 커밋, 변경 내역을 비교해 설계 변경을 검토하고 싶은 사용자
아키텍트와 리뷰어: 구현 코드가 설계와 일치하는지 검토하고, 코드에서 누락된 설계 정보를 역으로 정리하고 싶은 사용자

주요 작업 유형

1. 프로젝트 탐색

AI에게 프로젝트 전체 구조를 요약하게 할 수 있습니다.

가능한 작업:

접근 가능한 프로젝트 목록 확인
특정 프로젝트 선택
캔버스, 모델, 엔터티, 프로세서 구조 요약
특정 이름이나 키워드로 모델 요소 검색
현재 작업 중인 브랜치와 변경 상태 확인

예시 요청:

내가 접근할 수 있는 Beyond Entity 프로젝트 목록을 보여줘.

이 프로젝트의 데이터 모델과 API 프로세서를 한눈에 이해할 수 있게 요약해줘.

customer와 관련된 엔터티, 속성, 프로세서를 찾아서 정리해줘.

2. 데이터 모델 읽기와 문서화

AI가 모델, 엔터티, 속성, 제약조건, 관계를 읽고 사람이 이해하기 쉬운 문서로 정리할 수 있습니다.

가능한 작업:

특정 엔터티의 컬럼 목록과 의미 설명
기본키, 외래키, 인덱스, 제약조건 요약
엔터티 간 관계 설명
업무 용어 기준의 데이터 사전 초안 작성
테이블 설계 리뷰

예시 요청:

Order 엔터티의 컬럼, 키, 관계를 문서화해줘.

회원, 주문, 결제 관련 테이블의 관계를 비개발자도 이해할 수 있게 설명해줘.

이 모델에서 이름이 비슷하거나 중복 의미로 보이는 컬럼을 찾아줘.

3. 데이터베이스 모델 설계

AI에게 새 데이터 모델을 만들거나 기존 모델에 엔터티, 속성, 제약조건, 관계를 추가하게 할 수 있습니다.

가능한 작업:

MySQL, PostgreSQL, Oracle, SQL Server, BigQuery, Snowflake 등 다양한 저장소 유형의 모델 생성
새 테이블과 컬럼 설계
기본키, 외래키, 체크 제약조건, 인덱스 추가
관계 생성
기존 엔터티에 속성 추가
모델 이름, 테이블 이름, 컬럼 이름 수정

예시 요청:

구독 결제 기능에 필요한 데이터 모델을 설계해줘. 고객, 구독, 결제수단, 청구내역, 결제시도 테이블이 필요해.

Product 엔터티에 SKU, 판매상태, 판매시작일, 판매종료일 컬럼을 추가해줘.

Order와 Payment 사이에 주문 1건이 여러 결제시도를 가질 수 있는 관계를 만들어줘.

4. API, 배치, ETL 프로세스 모델링

Beyond Entity MCP는 데이터베이스 테이블뿐 아니라 API 서버, ETL 배치, ELT 작업, 스트리밍 처리, 파일 처리, 데이터 동기화 같은 프로세서도 다룰 수 있습니다.

가능한 작업:

API 요청과 응답 구조 모델링
배치 입력, 중간 조회값, 출력 구조 정의
SQL 기반 데이터 추출 및 변환 로직 추가
프로세서와 데이터 엔터티 사이의 읽기, 쓰기, 변환 관계 문서화
여러 단계의 처리 흐름 정리

예시 요청:

관리자 로그인 API를 프로세서로 모델링해줘. 입력은 email과 password, 출력은 accessToken과 user 정보야.

매일 주문 데이터를 집계해서 daily_sales_summary 테이블에 저장하는 배치 프로세스를 설계해줘.

이 SQL이 어떤 테이블을 읽고 어떤 출력 필드를 만드는지 데이터 흐름으로 등록해줘.

5. 데이터 계보와 영향도 분석

AI가 속성, 엔터티, 프로세서 사이의 데이터 흐름을 추적해 영향 범위를 설명할 수 있습니다.

가능한 작업:

특정 컬럼이 어디서 읽히고 어디에 쓰이는지 추적
API 응답 필드가 어떤 DB 컬럼에서 오는지 확인
배치나 ETL 로직의 입력과 출력 정리
컬럼 변경 시 영향을 받는 프로세서 찾기
데이터 흐름 문서화

예시 요청:

customer_email 컬럼이 어떤 API 응답이나 배치 출력에 사용되는지 찾아줘.

Payment.status 컬럼을 변경하면 영향을 받을 수 있는 프로세서를 정리해줘.

회원 가입부터 주문 생성까지 주요 데이터 흐름을 설명해줘.

6. 개인정보와 민감정보 탐색

프로젝트 안에서 개인정보, 민감정보, 암호화 대상 속성을 찾고 관리 기준에 맞게 검토할 수 있습니다.

가능한 작업:

PII 레벨이 지정된 속성 검색
암호화 또는 마스킹 대상 속성 확인
민감도 기준으로 컬럼 목록 만들기
개인정보가 포함된 엔터티와 프로세서 식별
보안 검토용 요약 문서 작성

예시 요청:

이 프로젝트에서 개인정보로 표시된 속성을 모두 찾아줘.

암호화가 필요한데 아직 암호화 설정이 없는 것으로 보이는 컬럼을 검토해줘.

사용자 식별 정보가 API 응답으로 노출되는 위치를 정리해줘.

7. 변경 사항과 버전 비교

Beyond Entity 프로젝트는 Git 기반 협업 흐름을 사용합니다. MCP를 통해 AI가 브랜치와 커밋 사이의 변경 사항을 확인하고 요약할 수 있습니다.

가능한 작업:

현재 작업공간의 미커밋 변경 사항 확인
브랜치 간 변경 사항 비교
커밋 간 변경 사항 비교
커밋 히스토리 확인
모델 변경 리뷰 초안 작성

예시 요청:

현재 브랜치에서 변경된 모델 요소를 요약해줘.

main 브랜치와 현재 브랜치의 차이를 데이터 모델 관점에서 설명해줘.

최근 커밋에서 어떤 엔터티와 속성이 변경되었는지 리뷰 노트로 정리해줘.

8. SQL, DDL, 코드 생성과 개발 지원

AI는 Beyond Entity MCP로 모델 구조를 읽은 뒤, 데이터베이스와 애플리케이션 개발에 필요한 산출물 초안을 만들 수 있습니다.

가능한 작업:

Beyond Entity 스키마를 기준으로 SQL DDL 생성
테이블 생성, 컬럼 추가, 인덱스, 제약조건 생성 SQL 작성
데이터베이스 마이그레이션 초안 생성
조회, 검증, 점검용 SQL 작성
ORM 엔티티 클래스 초안 생성
API DTO, request, response 타입 생성
테스트 데이터 구조 제안
모델 구조를 기준으로 API 설계 리뷰

예시 요청:

현재 Beyond Entity 모델을 기준으로 MySQL DDL을 생성해줘.

새로 추가된 엔터티와 속성만 반영하는 PostgreSQL migration SQL 초안을 만들어줘.

Order, Payment, Refund 엔터티의 기본키, 외래키, 인덱스를 포함한 CREATE TABLE 문을 작성해줘.

Customer와 Order 엔터티를 기준으로 JPA Entity 초안을 만들어줘.

이 프로세서 정의를 기준으로 FastAPI request/response Pydantic 모델을 만들어줘.

현재 모델을 PostgreSQL DDL 형태로 초안 작성해줘.

Beyond Entity 스키마를 기준으로 운영 배포 전에 확인할 수 있는 데이터 검증 SQL을 만들어줘.

9. 기존 코드에서 설계서 추출

AI가 코드 저장소와 Beyond Entity MCP를 함께 사용하면, 이미 구현된 코드에서 데이터 모델, API, 배치, 프로세서 설계서를 추출할 수 있습니다.

가능한 작업:

ORM 엔티티, SQL, 마이그레이션 파일에서 테이블과 컬럼 구조 추출
컨트롤러, 라우터, 서비스 코드에서 API 요청과 응답 구조 정리
배치, ETL, 스케줄러 코드에서 입력, 처리, 출력 흐름 문서화
코드에만 존재하는 모델 요소를 Beyond Entity 설계 후보로 정리
기존 구현을 기준으로 초기 데이터 사전 또는 시스템 설계서 초안 작성

예시 요청:

현재 코드의 ORM 엔티티와 마이그레이션 파일을 분석해서 데이터 모델 설계서 초안을 만들어줘.

API 라우터와 서비스 코드를 기준으로 사용자 관리 API의 요청, 응답, 사용 테이블을 정리해줘.

배치 코드에서 어떤 테이블을 읽고 어떤 테이블에 쓰는지 추출해서 프로세서 설계 후보로 만들어줘.

10. 현재 코드와 설계의 비교 검토

Beyond Entity에 정의된 설계와 실제 코드 구현을 비교해, 불일치나 누락 가능성을 검토할 수 있습니다.

가능한 작업:

코드의 테이블, 컬럼, 타입, 제약조건이 Beyond Entity 모델과 일치하는지 확인
API request/response 구조가 프로세서 설계와 일치하는지 검토
코드에는 있지만 설계에는 없는 엔터티, 속성, API 찾기
설계에는 있지만 코드에는 구현되지 않은 항목 찾기
컬럼명, 타입, null 허용 여부, enum 값, 관계 불일치 후보 정리
코드 변경 전후가 설계 변경과 함께 반영되었는지 리뷰

예시 요청:

현재 코드의 User 관련 ORM 모델이 Beyond Entity의 User 엔터티 설계와 일치하는지 비교해줘.

주문 생성 API 구현 코드가 Beyond Entity에 정의된 프로세서 입력, 출력, 데이터 흐름과 맞는지 검토해줘.

코드에는 존재하지만 Beyond Entity 설계에는 등록되지 않은 테이블, 컬럼, API를 찾아줘.

Beyond Entity 모델에는 있는데 현재 코드에서 구현을 찾을 수 없는 항목을 정리해줘.

MCP 연결 정보와 API 키 발급

Beyond Entity MCP를 사용하려면 MCP 서버 주소와 API 키가 필요합니다.

MCP 서버 주소는 사용자 또는 조직이 사용하는 cell server에 따라 다를 수 있습니다. 따라서 다른 사용자에게 받은 MCP URL을 그대로 사용하기보다, 본인의 Beyond Entity 웹앱에서 표시되는 MCP 주소를 확인해야 합니다.

확인 및 발급 경로:

Beyond Entity 웹앱에 로그인합니다.
Settings 메뉴로 이동합니다.
AI MCP Key 화면을 엽니다.
화면에 표시된 MCP 서버 주소를 확인합니다.
AI 도구 접속에 사용할 API 키를 생성합니다.
MCP를 지원하는 AI 도구에 MCP 서버 주소와 API 키를 등록합니다.

AI 도구에 등록할 때는 일반적으로 다음 정보가 필요합니다.

MCP 서버 URL: AI MCP Key 화면에 표시된 주소
인증 헤더: X-API-Key
API 키 값: AI MCP Key 화면에서 생성한 키

Beyond Entity 웹앱의 Settings > AI MCP Key 화면은 서버에서 제공하는 연결 가이드 Markdown을 그대로 표시할 수 있습니다. 이 가이드는 사용자의 조직 cell server를 기준으로 실제 MCP URL을 포함합니다.

MCP Server URL은 일반적으로 다음 두 가지가 제공됩니다.

권장 방식:

Streamable HTTP
https://{cell-server}/mcp

호환성 방식:

SSE
https://{cell-server}/sse

대부분의 최신 MCP 클라이언트는 Streamable HTTP를 사용하는 것이 좋습니다. 사용하는 AI 도구가 Streamable HTTP를 지원하지 않거나 SSE endpoint를 명시적으로 요구할 때만 SSE 주소를 사용하세요.

특정 프로젝트에 바로 연결하는 Direct Checkout 모드는 다음 형식을 사용할 수 있습니다.

Streamable HTTP
https://{cell-server}/mcp?project_id={PROJECT_ID}

SSE
https://{cell-server}/sse?project_id={PROJECT_ID}

주의할 점:

MCP 서버 URL은 사용자 환경마다 다를 수 있으므로 문서나 예시의 URL은 참고용으로만 사용해야 합니다.
API 키는 비밀번호처럼 취급해야 하며, 공개 저장소나 공유 문서에 넣으면 안 됩니다.
API 키를 분실했거나 노출되었다고 판단되면 기존 키를 폐기하고 새 키를 발급하는 것이 좋습니다.
API 키로 수행되는 작업은 해당 사용자 권한을 따릅니다.

예시 설정 형식:

{
  "mcpServers": {
    "beyond-entity": {
      "url": "AI MCP Key 화면에 표시된 MCP 서버 주소",
      "headers": {
        "X-API-Key": "발급받은 API 키"
      }
    }
  }
}

연결 방식

Beyond Entity MCP는 사용 방식에 따라 두 가지 연결 방식을 제공합니다.

어떤 방식을 선택해야 할지 모르겠다면 먼저 Streamable HTTP 주소를 사용하세요. SSE는 기존 MCP 클라이언트와의 호환성을 위한 방식입니다.

인터랙티브 모드

여러 프로젝트를 탐색하거나 대화 중에 프로젝트를 바꿔야 할 때 사용합니다.

적합한 경우:

Claude, ChatGPT, Gemini 같은 채팅형 AI 도구에서 사용
하나의 대화에서 여러 프로젝트를 탐색
프로젝트 ID를 미리 알지 못함
사용자가 AI에게 프로젝트 목록을 보여 달라고 하고 선택하고 싶음

기본 흐름:

MCP 서버에 연결합니다.
AI가 접근 가능한 프로젝트 목록을 조회합니다.
사용자가 작업할 프로젝트를 선택합니다.
AI가 해당 프로젝트를 체크아웃한 뒤 작업합니다.
필요하면 다른 프로젝트로 전환합니다.

직접 체크아웃 모드

하나의 IDE 워크스페이스를 하나의 Beyond Entity 프로젝트에 고정해 사용할 때 적합합니다.

적합한 경우:

VSCode, Cursor 같은 IDE에서 사용
하나의 작업공간이 하나의 프로젝트에 대응
매번 프로젝트를 선택하지 않고 바로 작업하고 싶음
프로젝트 ID를 이미 알고 있음

기본 흐름:

MCP 연결 URL에 project_id를 포함합니다.
첫 번째 도구 호출 시 Beyond Entity가 프로젝트를 자동으로 체크아웃합니다.
이후 모든 작업은 해당 프로젝트 컨텍스트에서 실행됩니다.

권한과 보안

Beyond Entity MCP는 사용자의 API 키와 프로젝트 권한을 기준으로 동작합니다.

사용자는 접근 권한이 있는 프로젝트만 조회할 수 있습니다.
읽기 전용 권한 사용자는 수정 작업을 수행할 수 없습니다.
프로젝트, 브랜치, 캔버스 권한이 적용됩니다.
MCP를 통한 작업도 Beyond Entity의 협업 및 변경 관리 흐름 안에서 수행됩니다.
같은 사용자와 프로젝트에서는 웹앱, MCP, IDE 세션이 동일한 원격 워크스페이스를 공유할 수 있습니다.

주의할 점:

같은 프로젝트에서 한 세션이 브랜치를 변경하면 다른 세션에도 영향을 줄 수 있습니다.
중요한 구조 변경을 요청하기 전에는 현재 브랜치와 변경 상태를 먼저 확인하는 것이 좋습니다.
삭제 작업은 복구와 리뷰 절차를 고려해 신중하게 요청해야 합니다.

좋은 요청을 작성하는 방법

AI에게 요청할 때는 작업 대상, 원하는 결과물, 제약조건을 함께 말하면 좋습니다.

좋은 요청 예시:

현재 프로젝트에서 주문 도메인의 핵심 엔터티를 찾아서, 각 엔터티의 목적, 주요 컬럼, 관계를 표로 정리해줘.

구독 결제 기능을 추가하려고 해. 기존 고객과 결제 모델을 먼저 확인한 뒤, 필요한 새 엔터티와 관계를 제안해줘. 바로 수정하지 말고 설계안부터 보여줘.

email, phone, address처럼 개인정보로 보이는 컬럼을 찾아서 PII 설정이 되어 있는지 확인해줘. 누락된 후보는 별도로 표시해줘.

현재 브랜치의 변경 사항을 main 브랜치와 비교해서, 리뷰어가 봐야 할 데이터 모델 변경만 요약해줘.

코드 저장소의 API 구현을 먼저 확인한 뒤, Beyond Entity에 정의된 프로세서 설계와 다른 부분만 표로 정리해줘.

자주 맡길 수 있는 작업 예시

다음 문장을 그대로 AI 도구에 입력해도 됩니다.

이 프로젝트의 전체 데이터 구조를 처음 보는 사람에게 설명하듯 요약해줘.

회원 관련 테이블과 API 프로세서를 찾아서 어떤 데이터가 오가는지 정리해줘.

이 모델에서 외래키 관계가 없어 보이는 참조 컬럼을 찾아줘.

새로운 쿠폰 기능을 위한 데이터 모델을 설계하고 Beyond Entity에 추가해줘.

최근 변경된 엔터티, 속성, 관계를 릴리스 노트 형식으로 정리해줘.

개인정보가 포함된 컬럼과 해당 컬럼을 사용하는 프로세서를 찾아 보안 검토 목록으로 만들어줘.

이 SQL 쿼리를 분석해서 어떤 입력, 조회, 출력 데이터가 있는지 프로세서 변환으로 정리해줘.

현재 모델을 기준으로 백엔드 개발자가 구현해야 할 API DTO 목록을 제안해줘.

Beyond Entity의 현재 스키마를 기준으로 SQL DDL과 마이그레이션 초안을 만들어줘.

설계된 외래키 관계와 인덱스를 포함해서 PostgreSQL CREATE TABLE 문을 생성해줘.

기존 코드에서 데이터 모델 설계서를 추출하고, Beyond Entity 모델에 반영할 후보를 정리해줘.

현재 코드가 Beyond Entity 설계와 다르게 구현된 부분을 찾아서 심각도별로 정리해줘.

사용 시 유의사항

Beyond Entity MCP는 AI가 프로젝트를 더 정확하게 이해하고 작업할 수 있게 해 주지만, 모든 판단을 자동으로 대체하지는 않습니다.

AI가 만든 설계안은 팀의 모델링 규칙과 업무 기준에 맞는지 검토해야 합니다.
대량 변경이나 삭제 작업은 변경 내용을 먼저 확인한 뒤 적용하는 것이 좋습니다.
코드 생성 결과는 실제 개발 환경의 프레임워크, 버전, 네이밍 규칙에 맞게 조정해야 합니다.
보안, 개인정보, 권한 관련 판단은 조직의 정책과 함께 검토해야 합니다.

한 줄 요약

Beyond Entity MCP는 AI가 Beyond Entity 프로젝트의 실제 모델과 변경 이력을 직접 이해하고, 데이터 모델링, 프로세스 설계, 계보 분석, 보안 검토, 코드 생성 지원까지 수행할 수 있게 해 주는 AI 작업 연결 기능입니다.

Beyond Entity MCP 사용 가이드

Beyond Entity MCP로 할 수 있는 일

MCP란 무엇인가요?

이런 사용자에게 적합합니다

주요 작업 유형

1. 프로젝트 탐색

2. 데이터 모델 읽기와 문서화

3. 데이터베이스 모델 설계

4. API, 배치, ETL 프로세스 모델링

5. 데이터 계보와 영향도 분석

6. 개인정보와 민감정보 탐색

7. 변경 사항과 버전 비교

8. SQL, DDL, 코드 생성과 개발 지원

9. 기존 코드에서 설계서 추출

10. 현재 코드와 설계의 비교 검토

MCP 연결 정보와 API 키 발급

연결 방식

인터랙티브 모드

직접 체크아웃 모드

권한과 보안

추천 사용 흐름

좋은 요청을 작성하는 방법

자주 맡길 수 있는 작업 예시

사용 시 유의사항

한 줄 요약