MCP 연결 가이드

AI 에이전트가 ERD를 직접 작성하게 연결하기

ErdForge는 AI 에이전트가 ERD를 읽고 작성할 수 있는 MCP 연결 주소를 제공합니다. 개인 토큰을 MCP 클라이언트에 등록하면 워크스페이스를 조회하고, 테이블과 관계를 포함한 ERD를 저장할 수 있습니다.

Endpoint/mcp

1. 개인 토큰 생성

ErdForge에 로그인한 뒤 대시보드의 MCP 토큰 패널에서 워크스페이스 범위와 만료일을 정해 토큰을 만듭니다.

Authorization: Bearer erdforge_mcp_...

2. 클라이언트 연결

MCP 클라이언트에 연결 주소와 개인 Bearer 토큰을 등록합니다.

{
  "url": "<현재 도메인주소>/mcp",
  "transport": "streamable-http",
  "headers": {
    "Accept": "application/json, text/event-stream",
    "Authorization": "Bearer erdforge_mcp_...",
    "MCP-Protocol-Version": "2025-11-25"
  }
}

로컬 production 컨테이너를 확인할 때는 주소를 http://localhost:4173/mcp로 둡니다.

현재 지원 범위

MCP 클라이언트는 `/mcp` 주소로 요청을 보냅니다. 열린 웹 화면은 MCP upsert/delete 변경을 SSE로 감지해 목록과 현재 ERD를 갱신합니다.
현재 MCP로 제공하는 항목은 도구, 리소스, 프롬프트입니다.
인증은 대시보드에서 발급한 개인 Bearer 토큰을 기본으로 사용하며, 토큰은 사용자 권한과 워크스페이스 scope를 따릅니다.
전체 범위 토큰은 workspaceName으로 새 워크스페이스를 만들 수 있고, 워크스페이스 범위 토큰은 선택된 워크스페이스 안에서만 읽기/쓰기가 가능합니다.

제공 도구

erdforge_list_workspaces

사용 가능한 워크스페이스와 현재 선택 상태를 조회합니다.

erdforge_create_workspace

AI 에이전트가 새 ERD 워크스페이스를 만들고 저장 준비를 합니다.

erdforge_list_diagrams

워크스페이스별 ERD 목록, 테이블 수, 관계 수를 조회합니다.

erdforge_get_diagram

기존 ERD JSON을 읽어 수정 전 맥락으로 사용합니다.

erdforge_upsert_diagram

테이블, 컬럼, 관계를 포함한 ERD를 생성하거나 갱신합니다. workspaceName을 보내면 새 워크스페이스 생성과 저장을 한 번에 처리합니다.

erdforge_delete_diagram

워크스페이스의 ERD를 삭제하고 열린 웹 화면에 변경 알림을 보냅니다.

제공 리소스

erdforge://workspaces

현재 토큰으로 접근 가능한 워크스페이스 목록을 JSON resource로 읽습니다.

erdforge://workspace/{workspaceId}/diagrams

특정 워크스페이스의 ERD 목록과 요약 정보를 읽습니다.

erdforge://workspace/{workspaceId}/diagram/{diagramId}

특정 ERD의 전체 JSON을 context resource로 읽습니다.

제공 프롬프트

erdforge_create_erd_from_requirements

요구사항을 ErdForge ERD 초안으로 바꾸는 작업을 시작합니다.

erdforge_review_diagram

기존 ERD의 키, 관계, 누락 테이블, 정규화 위험을 검토합니다.

erdforge_extend_diagram

새 기능 요구사항을 기존 ERD 변경안으로 확장합니다.

ERD 생성 예시

에이전트는 단순한 테이블 명세를 보내도 ErdForge가 캔버스용 id, 좌표, 컬럼 id를 보정합니다.

{
  "name": "Order Core",
  "dialect": "PostgreSQL",
  "tables": [
    {
      "name": "users",
      "description": "Customer accounts",
      "columns": [
        { "name": "id", "type": "uuid", "primaryKey": true },
        { "name": "email", "type": "varchar(255)", "unique": true }
      ]
    },
    {
      "name": "orders",
      "columns": [
        { "name": "id", "type": "uuid", "primaryKey": true },
        { "name": "user_id", "type": "uuid", "foreignKey": true },
        { "name": "total_amount", "type": "numeric(12,2)" }
      ]
    }
  ],
  "relations": [
    {
      "sourceTable": "orders",
      "sourceColumn": "user_id",
      "targetTable": "users",
      "targetColumn": "id",
      "fromCardinality": "zeroMany",
      "toCardinality": "one"
    }
  ]
}

새 워크스페이스에 바로 저장

전체 범위 토큰에서는 erdforge_upsert_diagram 호출에 workspaceName을 함께 보내 새 워크스페이스를 만들고 첫 ERD를 바로 저장할 수 있습니다.

{
  "name": "erdforge_upsert_diagram",
  "arguments": {
    "workspaceName": "Billing DB 구조",
    "diagramId": "billing_schema",
    "name": "Billing PostgreSQL Schema",
    "dialect": "PostgreSQL",
    "tables": [
      { "name": "accounts", "columns": [{ "name": "id", "type": "uuid", "primaryKey": true }] }
    ],
    "relations": []
  }
}

운영 메모

개인 토큰은 만든 사용자 권한으로만 동작하며, 선택한 워크스페이스 범위를 벗어날 수 없습니다.
만료되었거나 폐기된 토큰은 즉시 MCP 호출이 거부됩니다.
GET 또는 DELETE 요청은 405로 응답합니다. 현재 ErdForge MCP는 request-response HTTP POST만 사용합니다.
AI 에이전트가 만든 ERD는 ErdForge 웹 화면에서 바로 열어 검토할 수 있습니다.