Dashboard Builder MCP 서버

AI 클라이언트가 Dashboard Builder에서 데이터셋을 발견하고 대시보드를 작성할 수 있게 해줍니다.

일반 API 클라이언트로서 Next.js 앱과 HTTP로 통신하므로, 앱의 모든 권한 가드, 의존성 정책 및 검증 규칙이 그대로 적용됩니다. 메인 애플리케이션에는 아무것도 변경되지 않습니다.

두 가지 방식으로 실행할 수 있습니다:

호스팅이 일반적인 배포 방식이며 이 문서에서 다루는 내용입니다. 로컬 모드는 서버 자체를 개발하거나 사용자별 신원을 위한 것으로, DEVELOPMENT.md에 설명되어 있습니다.

사용자용: 호스팅 서버에 연결하기

배포한 사람에게 두 가지를 받아야 합니다: URL과 게이트 키. 클론할 것도, 지정할 파일도, .env도 필요 없습니다.

claude_desktop_config.json(Claude Desktop) 또는 .mcp.json(Claude Code)에 다음을 추가하세요:

{
  "mcpServers": {
    "dashboard-builder": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.yourcompany.com/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_HERE",
        "--header", "X-Dashboard-Username: you",
        "--header", "X-Dashboard-Password: your-dashboard-password"
      ]
    }
  }
}

mcpServers는 최상위 키로, preferences의 형제입니다 — 그 안에 중첩되지 않습니다. 시스템 트레이에서 Claude Desktop을 완전히 종료하고 다시 여세요. 창을 닫는 것만으로는 충분하지 않습니다.

두 개의 X-Dashboard-* 헤더가 있으면 서버는 첫 사용 시 자동으로 사용자로 로그인하고 세션이 만료될 때마다 다시 로그인합니다 — 다른 할 일은 없으며, 모든 호출은 사용자로서 작동합니다: 사용자의 권한, 사용자의 감사 추적. 단점은 대시보드 비밀번호가 이 구성 파일에 저장되고 각 요청과 함께(HTTPS를 통해) 전송된다는 점입니다. 비밀번호에 ASCII 외의 문자가 포함된 경우 아래의 curl 바인드를 대신 사용하세요 — HTTP 헤더는 해당 문자를 안정적으로 전달하지 못합니다.

대안: curl로 한 번 바인드하고 구성 파일에 비밀번호를 두지 않기

두 개의 X-Dashboard-* 헤더를 생략하고 대신 키를 한 번 바인드하세요 — 비밀번호는 그 단일 로그인에만 사용되며 어디에도 저장되지 않습니다. 서버는 브라우저가 쿠키를 유지하는 것과 정확히 같이, 결과 세션 토큰만 보관합니다:

curl -X POST https://mcp.yourcompany.com/auth/bind \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"username":"you","password":"your-dashboard-password"}'

헤더 방식과의 차이점: 세션 체인이 결국 만료되면 이 명령을 다시 실행해야 하는 반면, 헤더 방식은 자동으로 다시 바인드됩니다. 동일한 Authorization 헤더를 사용한 DELETE /auth/bind는 두 경우 모두 키를 로그아웃시킵니다.

Alice's Claude ──[gate key]──> MCP server ──[Alice's session cookies]──> Dashboard API
                     ^                                ^
              client config              bound via credential headers or
                                         POST /auth/bind; refreshed
                                         automatically after that

키가 바인드된 적이 없으면 도구 호출은 바인드 단계를 설명하는 오류로 실패합니다 — 또는 서버가 레거시 서비스 계정으로 구성된 경우 해당 공유 신원으로 대체됩니다.

mcp-remote는 로컬에서 실행되어 서버로 전달하는 작은 브리지이므로 사용자 머신에 Node가 설치되어 있어야 합니다. 그것조차 피하려면 Claude Desktop의 Settings → Connectors → Add custom connector가 로컬에 아무것도 없이 URL을 직접 받습니다 — 그 경로는 정적 키 대신 OAuth를 기대하며, 가용성은 Desktop 버전에 따라 다릅니다.

서버 배포하기

server.js가 시작 파일입니다. Next.js server.js처럼 PORT에서 수신하며, 모든 MCP 요청 앞에 API 키 게이트를 두어 인증되지 않은 호출자가 대시보드 시스템에 도달하기 전에 거부되도록 합니다.

엔드포인트: POST /mcp(게이트 적용), POST /auth/bind 및 DELETE /auth/bind(게이트 적용 — 호출 키의 대시보드 신원을 바인드 또는 언바인드), GET /health(공개, 플랫폼 상태 확인용). 그 외 모든 것은 404를 반환합니다.

환경 변수

필수 — 이것들이 없으면 서버가 시작되지 않습니다

openssl rand -hex 24로 키를 생성하세요. 콜론 앞의 라벨은 로그와 rate-limit 버킷에 표시됩니다. 비밀번호 자체는 절대 로그에 남지 않습니다. 한 사람을 해지하려면 해당 항목을 제거하고 재시작하면 됩니다 — 그리고 ~/.dashboard-mcp/sessions/ 아래의 세션 파일을 삭제하여 바인드된 신원도 제거하세요.

그런 다음 각 키는 보유자가 POST /auth/bind를 통해 대시보드 계정에 바인드합니다 — 위의 사용자 섹션을 참조하세요. 대시보드 자격 증명은 서버 환경에 존재하지 않습니다.

선택적 레거시 대체 — 공유 서비스 계정

설정되면 바인드되지 않은 키는 실패하는 대신 이 공유 계정으로 작동합니다 — 바인드가 만료된 키도 다시 바인드될 때까지 마찬가지입니다. 마이그레이션 중에 유용합니다. 모든 호출자가 자신의 신원을 갖도록 새 배포에서는 생략하세요.

강력 권장

DASHBOARD_MCP_PERSIST_SESSION은 기본값(true)으로 두세요: 바인드는 키당 파일 하나로 저장되며 재시작 후에도 유지됩니다. false로 설정하면 바인드가 메모리에만 유지되므로 모든 재시작 — 그리고 다중 워커 호스트의 모든 워커 — 에서 각각 다시 바인드해야 합니다.

MCP_ALLOWED_HOSTS와 MCP_ALLOWED_ORIGINS는 선택 사항입니다 — 서버는 이것들 없이도 실행되며 API 키 게이트는 여전히 적용됩니다. 둘 중 하나를 설정하면 전송 계층의 DNS 리바인딩 보호가 켜집니다. 둘 다 설정하지 않으면 시작 로그에 명시적으로 표시됩니다.

선택 사항

추가 튜닝 변수 — 세션 파일 경로, 요청 시간 초과, 응답 상한 및 대시보드 종류 id 재정의 — 는 .env.example에 인라인으로 문서화되어 있으며, 모드별로 구성되어 서버가 읽는 모든 변수를 나열합니다.

다중 워커 참고 사항

바인드는 키당 파일 하나이며, 다른 워커에 의해 메모리 내 토큰이 교체된 워커는 승리한 워커가 이미 업데이트한 해당 파일을 다시 읽어 복구합니다. 실패 창은 두 워커가 동시에 같은 토큰을 갱신하는 경우이며, 패자는 다음 시도에서 복구하고 최악의 경우 키를 다시 바인드해야 합니다. MCP 전송 자체는 상태 비저장이므로 요청은 어떤 워커에든 도달할 수 있습니다.

Plesk 설정

도메인의 Additional nginx directives에 추가:

proxy_buffering off;
proxy_read_timeout 300s;

MCP는 Server-Sent Events로 응답하며 nginx는 기본적으로 프록시된 응답을 버퍼링합니다. proxy_buffering off가 없으면 요청이 실패하는 대신 멈춘 것처럼 보이며, 이는 오후를 날려버리는 혼란스러운 방식입니다.

Node 포트는 공개 방화벽에서 격리하세요. Plesk의 nginx가 프록시하고 X-Forwarded-For를 설정하며, 이것이 로그된 클라이언트 IP를 신뢰할 수 있게 만드는 이유입니다.

접근과 신원

게이트 키는 접근을 제어합니다. 신원은 바인드에서 옵니다. 키는 호출자를 게이트를 통과시키고, 해당 키에 바인드된 세션이 대시보드가 보는 대상을 결정합니다 — 그들의 권한, 그들의 감사 추적. 둘은 의도적으로 분리되어 있습니다: 키의 비밀번호를 교체하면 바인드가 해제되고(세션은 키의 다이제스트 아래에 정리됨), 키를 해지하면 계정에 영향을 주지 않고 접근만 제거됩니다.

바인드는 브라우저 로그인과 같은 방식으로 작동합니다. POST /auth/bind는 앱의 실제 /api/auth/login을 한 번 실행하고, 비밀번호는 교환 후 폐기되며, 회전하는 refresh-token 세션만 유지됩니다 — 키당 파일 하나, 모드 0600. 앱이 사용할 때마다 refresh token을 회전시키므로 유출된 세션 파일은 빠르게 무효화됩니다. 비밀번호가 저장되지 않으므로 장기간 유출될 것이 없습니다. 단점: refresh 체인이 만료되거나 끊어지면 해당 키는 curl 한 번으로 다시 바인드됩니다.

안정적인 요청별 자격 증명(메인 시스템의 ApiKey 또는 OAuth)은 그 재바인드조차 제거하겠지만, 메인 애플리케이션의 변경이 필요합니다. 이 설계는 의도적으로 어떤 변경도 필요로 하지 않습니다.

로컬에서 개발 또는 실행하기

자신의 머신에서 서버를 실행하는 것 — 개발용 또는 호스팅 없이 사용자별 신원을 위한 것 — 은 DEVELOPMENT.md에 별도로 문서화되어 있습니다.

도구

설계 노트

컨텍스트 절제. 전체 도구 표면은 약 3.6KB — 설명 13개와 서버 지침을 합친 크기 — 이므로 계속 로드해 두어도 비용이 낮게 유지된다. 응답은 원시 JSON이 아닌 간결한 텍스트이며, 모든 목록에는 생략된 내용을 명시하는 메모가 붙는다. get_dashboard는 의도적으로 위젯 구성을 생략한다. 구성이 필요할 때는 ID로 위젯 하나를 요청하면 된다.

점진적 공개. 차트 구성에는 대략 59개의 필드가 있다. 이를 도구 설명에 넣으면 매 요청마다 클라이언트의 컨텍스트를 압도하게 되므로, describe_widget_kind가 대신 필요 시 계약을 제공한다: 필드 이름, 유형, 참고 사항, 최소 동작 예시, 그리고 — 유용한 부분 — 사용자 자신의 워크스페이스에 있는 해당 종류의 기존 위젯에서 수집한 실제 구성. 이미 렌더링되는 형태를 복사하는 것이 필드 이름으로 새로 만들어내는 것보다 낫다.

서버가 배치를 처리한다. 모델은 2D 패킹에 신뢰할 수 없다. add_widget는 size 힌트(small, medium, large, full)를 받아 12열 그리드에서 겹치지 않는 첫 번째 빈 셀을 직접 찾는다. arrange_dashboard의 auto 모드는 대시보드 전체를 다시 패킹한다.

API 호출 전에 실패를 감지한다. 위젯 구성은 앱에서 불투명한 JSON으로 저장되므로, 키를 잘못 입력하면 오류 대신 빈 위젯이 생성된다. add_widget는 먼저 해당 종류의 계약에 대해 구성을 검증한다 — 필수 키, 유효한 집계 이름, 집계가 필요로 할 때 field 존재 여부 — 그리고 누락된 항목의 구체적인 목록을 반환한다.

위젯은 UI가 생성하는 것과 일치한다. 앱의 팔레트는 모든 새 위젯을 레지스트리의 해당 종류 defaultConfig로 초기화한다(config === undefined ? def.defaultConfig : config). add_widget도 이를 그대로 따른다: 호출자가 제공하는 모든 것 아래에 종류 기본값이 깔리므로, MCP로 작성된 차트는 렌더러가 대체해야 하는 희소한 구성 대신 수동으로 만든 차트와 동일한 paginationMode 및 maxPoints 기준선을 갖는다. 병합된 객체가 검증 대상이다.

재전송 대신 병합. PATCH /widgets/:id는 구성 객체를 통째로 교체한다. update_widget는 기본적으로 키를 기존 구성에 병합하므로, 설정 하나를 변경한다고 전부를 다시 보낼 필요가 없다.

시작 시 실패 시 폐쇄. HTTP 서버는 MCP_API_KEYS 항목이 하나 이상 없으면 시작을 거부하며, 24자 미만의 키는 거부한다. 인증되지 않은 MCP 엔드포인트가 우연히 존재할 수 없어야 한다. 키는 timingSafeEqual로 SHA-256 다이제스트로 비교되며, 레이블만 로깅된다.

알려진 제한 사항

• 위젯 종류 카탈로그는 복사본이다. src/catalog/widget-kinds.ts는 src/features/dashboard/widgets/registry.ts — 각 종류의 defaultConfig를 포함 — 및 종류별 구성 인터페이스를 그대로 반영한다. 앱의 레지스트리는 클라이언트 컴포넌트이고 React를 가져오므로 여기서 가져올 수 없다. 위젯 종류에 필드가 추가되거나 defaultConfig 값이 변경되면 카탈로그도 함께 업데이트해야 한다. 그렇지 않으면 MCP로 생성된 위젯이 UI로 생성된 위젯과 어긋나게 된다.

• 카탈로그 적용 범위는 높지만 완전하지는 않다. 문서화된 필드 대 실제 구성 필드: table 18/21, stat 22/25, chart 39/59, select 9/12, text 16/17. 빠진 것은 대부분 시각적 변형(파이/라인/바 스타일 옵션, 오른쪽 축 재정의)과 highlightBindings로 대체된 레거시 상호작용 키다. describe_widget_kind가 반환하는 실제 예시가 이에 대한 참조다. 필드는 core / display / interaction으로 그룹화되어 데이터 계약이 먼저 읽히도록 한다.

• 바인딩은 갱신 체인과 함께 만료된다. 키의 세션은 앱이 순환 갱신 토큰을 유지하는 동안 지속된다. 만료되면 호출이 실패하고 해결 방법을 명시하는 오류가 반환되며, 키 보유자는 curl 한 번으로 다시 바인딩한다. 만료되지 않는 신원이 필요하다면 메인 시스템의 src/lib/api-guard.ts에 ApiKey를 연결해야 하는데, 이는 아직 완료되지 않았다.

• 쓰기는 직접 수행된다. 앱에는 변경 초안 및 승인 워크플로우(ChangeDraft, ApprovalRequest)가 있다. 이 도구들은 로그인된 계정의 권한으로 직접 기록한다. AI가 작성한 대시보드가 게시 전에 검토되어야 한다면, 쓰기 도구를 /api/change-drafts로 라우팅하고 계정의 권한은 읽기 전용으로 유지하라.