MCP 연결 가이드 Claude Code

개요

MCP(Model Context Protocol)는 Claude Code 같은 AI 클라이언트가 외부 도구를 호출하도록 연결하는 표준입니다. YourERD는 서버에 원격 MCP 엔드포인트(/mcp)를 직접 제공하므로, 연결하면 다음처럼 말할 수 있습니다:

예전처럼 저장소를 클론하거나 Node를 설치하거나 .mcp.json을 손으로 편집하거나 Claude Code를 재시작할 필요가 없습니다. 웹에서 발급한 개인 토큰이 박힌 명령 한 줄을 붙여넣으면 끝입니다.

Claude Code ──HTTP(개인 토큰)──▶ YourERD 서버 /mcp  (별도 프로세스·레포 불필요)

1로그인 & 토큰 발급

• YourERD에 로그인합니다(없으면 우측 상단 아바타 → 회원가입). 본인 계정의 다이어그램만 MCP에서 보이고 편집됩니다.
• 좌측 사이드바 하단 “MCP 연결” 메뉴를 엽니다.
• “토큰 발급”을 누르면 개인 액세스 토큰(PAT)이 만들어지고, 토큰이 채워진 연결 명령이 표시됩니다.

2명령 한 줄 붙여넣기

모달의 복사 버튼으로 명령을 복사해 터미널에 붙여넣습니다. (아래는 형태 예시 — 실제로는 발급된 토큰이 채워져 있습니다.)

claude mcp add --scope user --transport http \
  erd https://yourerd.com/mcp \
  --header "Authorization: Bearer <발급한_토큰>"

--header는 반드시 맨 뒤에 옵니다(가변인자라 앞에 두면 이름·주소를 삼켜 오류).

또는 .mcp.json에 직접 추가해도 됩니다(모달의 “또는 .mcp.json에 직접 추가” 펼치기).

{
  "mcpServers": {
    "erd": {
      "type": "http",
      "url": "https://yourerd.com/mcp",
      "headers": { "Authorization": "Bearer <발급한_토큰>" }
    }
  }
}

3연결 확인

원격 MCP는 즉시 등록되므로 재시작이 필요 없습니다. Claude Code에서:

• /mcp 입력 → erd 서버와 도구 목록이 보이면 연결 성공
• 또는 "ERD 다이어그램 목록 보여줘"라고 요청 → list_diagrams 실행

사용법

연결되면 자연어로 요청하면 됩니다. 예:

• "주문 시스템 ERD 새로 만들어줘"
• "User(사용자)와 Order(주문) 엔티티 추가하고, User→Order 1:M 비식별 관계 연결해줘"
• "User에 email(이메일) varchar(255) 컬럼 추가해줘"
• "방금 만든 다이어그램 요약 보여줘"

관계를 연결하면 상위 엔티티의 PK가 하위에 FK 컬럼으로 자동 생성됩니다(식별 관계면 FK가 하위 PK에도 포함).

도구 목록

참조 인자(엔티티·컬럼·source·target)는 id 또는 이름 둘 다 사용할 수 있습니다.

고급: 로컬 stdio 방식

저장소를 클론해 로컬에서 MCP 서버를 직접 실행하는 예전 방식도 계속 지원됩니다(개발·디버깅용). Node 18+와 저장소 클론이 필요하며, 서비스 계정 자격증명을 .mcp.json에 넣습니다.

cd erd-service/mcp && npm install

# 프로젝트 루트 .mcp.json
{
  "mcpServers": {
    "erd": {
      "command": "npx",
      "args": ["-y", "tsx", "erd-service/mcp/src/index.ts"],
      "env": {
        "ERD_BASE_URL": "https://yourerd.com",
        "ERD_USERNAME": "내아이디-mcp",
        "ERD_PASSWORD": "내비밀번호"
      }
    }
  }
}

문제 해결

주의사항

• 새로고침 필요: MCP 편집은 DB에 저장됩니다. 이미 열려 있는 브라우저에는 자동 반영되지 않으니 다이어그램을 다시 열거나 새로고침하세요.
• 마지막 저장 우선: 같은 다이어그램을 MCP와 브라우저에서 동시에 저장하면 나중 저장이 앞 저장을 덮어씁니다.
• 계정 격리: 각자 자기 MCP 계정의 다이어그램만 보고 편집합니다. 공유하려면 같은 계정을 함께 쓰면 됩니다.
• 일괄 생성·실시간 동기화는 현재 범위 밖입니다.