MCP 서버로 AI 도구 연동하기

mAsh API는 MCP(Model Context Protocol) 서버를 제공합니다. MCP를 통해 Claude Code, Cursor 등 AI 코딩 도구에서 mAsh 데이터를 직접 조회하고 분석할 수 있습니다.

MCP란?

MCP(Model Context Protocol)는 Anthropic에서 개발한 AI 도구 통합 프로토콜입니다. AI 어시스턴트가 외부 데이터 소스에 안전하게 접근할 수 있도록 표준화된 인터페이스를 제공합니다.

주요 장점

AI 네이티브: AI 도구가 자연어로 데이터를 조회하고 분석
보안: 기존 mAsh 인증 체계(API Key/JWT) 재사용
멀티테넌시: 사용자별 접근 권한 자동 적용

제공 Tools

Tool	설명
`list_boards`	접근 가능한 보드 목록 조회
`list_dashboards`	보드의 대시보드 목록 조회
`get_dashboard`	대시보드 상세 정보 조회 (위젯 목록 포함)
`list_widgets`	대시보드의 위젯 목록 조회
`search_widgets`	위젯 검색 (이름, 즐겨찾기 필터)
`get_widget_data`	위젯 데이터 조회 (기간 지정)

설정 방법

사전 준비: API Key 발급

관리자 계정에서 mAsh 대시보드의 환경 설정 > 개인 설정 화면에서 API Key를 발급받을 수 있습니다. 자세한 방법은 API 인증 가이드를 참고하세요.

권장: API Key는 만료되지 않으므로 JWT 토큰보다 API Key 사용을 권장합니다. JWT 토큰은 5분 후 만료됩니다.

참고: API Key 발급은 관리자 권한이 필요합니다. 권한이 없는 경우 조직 관리자에게 문의하세요.

1. 환경변수 설정

API Key를 환경변수로 설정합니다.

# .env 파일에 추가
MASH_API_KEY=abcd1234.xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 또는 쉘 프로필(~/.zshrc, ~/.bashrc)에 추가
export MASH_API_KEY="abcd1234.xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. `.mcp.json` 파일 생성

프로젝트 루트에 .mcp.json 파일을 생성합니다.

{
  "mcpServers": {
    "mash-api": {
      "type": "http",
      "url": "https://api.mash-board.io/mcp/",
      "headers": {
        "X-MASH-API-KEY": "${MASH_API_KEY}"
      }
    }
  }
}

환경변수 MASH_API_KEY가 설정되어 있으면 자동으로 치환됩니다.

3. AI 도구 재시작

설정 파일 생성 후 AI 도구를 재시작하면 MCP 서버가 자동으로 연결됩니다.

지원 도구

Claude Code: 첫 연결 시 서버 승인 팝업이 표시될 수 있습니다.
Cursor: 동일한 .mcp.json 설정을 사용합니다.

사용 예시

MCP 서버가 설정되면 AI 도구에서 자연어로 mAsh 데이터를 조회할 수 있습니다.

기본 사용법

보드 목록 조회

"내가 접근할 수 있는 보드 목록을 보여줘"

AI가 list_boards tool을 호출하여 접근 가능한 보드 목록을 반환합니다.

대시보드 목록 조회

"첫 번째 보드의 대시보드 목록을 보여줘"

AI가 list_boards로 보드 UID를 확인한 후 list_dashboards를 호출합니다.

위젯 데이터 분석

"일일 리포트 대시보드의 방문자 수 위젯 데이터를 이번 달 조회해서 분석해줘"

AI가 순차적으로 보드 → 대시보드 → 위젯을 찾아 get_widget_data로 데이터를 조회합니다.

위젯 검색

"'방문' 관련 위젯을 찾아줘"

AI가 search_widgets tool을 호출하여 이름에 "방문"이 포함된 위젯을 검색합니다.

실전 유스케이스

유스케이스 1: 주간 데이터 리포트 생성

프롬프트 예시:

"OO스토어 저번주 데이터 리포트 만들어줘"

AI가 수행하는 작업:

list_boards → "OO스토어" 보드 UID 확인
list_dashboards → 해당 보드의 대시보드 목록 조회
list_widgets → 대시보드 내 위젯 목록 파악
get_widget_data → 주요 위젯들의 저번주 데이터 조회

결과물 예시:

AI가 자동으로 다음과 같은 리포트를 마크다운으로 생성합니다:

# OO스토어 강남점 주간 리포트
**기간**: 2025-02-17 ~ 2025-02-23

## 핵심 지표
| 지표 | 수치 |
|------|------|
| 총 방문객 | 5,419명 |
| 실질 방문객 | 4,889명 (90.2%) |
| 상담 전환율 | 15.9% |

## 인기 구역 TOP 3
1. 2층 신상품존 - 644명
2. 2층 체험존 - 600명
3. 1층 메인홀 - 553명

유스케이스 2: 구역별 체류 시간 분석

프롬프트 예시:

"우리 매장에서 고객이 가장 오래 머무는 구역 TOP 5 알려줘"

AI가 수행하는 작업:

list_boards → 매장 보드 확인
search_widgets → "체류" 또는 "머무" 키워드로 위젯 검색
get_widget_data → 구역별 체류 시간 데이터 조회
데이터 정렬 및 분석

결과물 예시:

## 체류 시간 TOP 5 구역

| 순위 | 구역 | 평균 체류시간 | 60초+ 체류 고객 |
|------|------|--------------|----------------|
| 1 | 2층 상담존 | 15분 12초 | 883명 |
| 2 | 2층 신상품존 | 4분 53초 | 762명 |
| 3 | 1층 메인홀 | 3분 31초 | 556명 |
| 4 | 2층 라운지 | 8분 50초 | 456명 |
| 5 | 2층 체험존 | 3분 40초 | 352명 |

**인사이트**: 상담존 구역에서 체류 시간이 가장 길며,
신상품 및 체험 구역이 방문객 수와 체류 시간 모두 높습니다.

유스케이스 3: 교차 방문 분석

프롬프트 예시:

"A/S센터 방문 고객 중 매장도 함께 둘러본 고객 비율 분석해줘"

AI가 수행하는 작업:

search_widgets → "A/S센터", "교차", "동시 방문" 관련 위젯 검색
get_widget_data → 퍼널 또는 세그먼트 데이터 조회
전환율 계산 및 인사이트 도출

결과물 예시:

## A/S센터 ↔ 매장 교차 방문 분석

### 방문 흐름
- 전체 방문객: 5,419명
- A/S센터 방문객: 1,043명 (19.2%)
- A/S센터 → 매장 재방문: 1,017명 (**전환율 97.5%**)

### 체류 시간 비교
| 세그먼트 | 평균 체류시간 |
|----------|--------------|
| A/S센터만 방문 | 3분 50초 |
| A/S센터 + 매장 동시 방문 | **15분 51초** |

**인사이트**: A/S센터 방문 고객의 97.5%가 매장도 함께 둘러보며,
동시 방문 시 체류 시간이 4배 증가합니다. A/S센터를 매장 유입 채널로
활용하는 전략이 효과적입니다.

유스케이스 4: 품목별 성과 비교

프롬프트 예시:

"A카테고리와 B카테고리 품목 중 어느 쪽 실적이 더 좋아?"

AI가 수행하는 작업:

search_widgets → "카테고리", "품목" 관련 위젯 검색
get_widget_data → 품목별 방문객/체류시간 데이터 조회
비교 분석 및 결론 도출

결과물 예시:

## A카테고리 vs B카테고리 비교

| 지표 | A카테고리 | B카테고리 | 비고 |
|------|-----------|-------------|------|
| 구역 방문객 | 1,749명 | 2,561명 | B +46% |
| 실질 방문객 | 680명 | 1,428명 | B +110% |
| 실질 방문율 | 12.5% | 26.4% | B 2배 |
| 평균 체류시간 | 2분 47초 | 3분 34초 | B +28% |

**결론**: B카테고리 제품군이 모든 지표에서 A카테고리를 앞서며,
특히 실질 방문객 수에서 2배 이상 차이가 납니다.

유스케이스 5: 특정 기간 트렌드 분석

프롬프트 예시:

"이번 달과 저번 달 방문객 수 비교해줘"

AI가 수행하는 작업:

list_widgets → 방문객 관련 위젯 확인
get_widget_data (이번 달) → 현재 월 데이터 조회
get_widget_data (저번 달) → 이전 월 데이터 조회
증감률 계산 및 트렌드 분석

결과물 예시:

## 월간 방문객 트렌드

| 지표 | 1월 | 2월 | 증감 |
|------|-----|-----|------|
| 총 방문객 | 18,234명 | 21,567명 | +18.3% |
| 실질 방문객 | 16,411명 | 19,892명 | +21.2% |
| 상담 전환객 | 2,918명 | 3,421명 | +17.2% |

**트렌드**: 2월 방문객이 전월 대비 18% 증가했으며,
실질 방문객 증가율이 더 높아 고객 품질이 개선되고 있습니다.

유스케이스 6: 고객 여정 분석

프롬프트 예시:

"고객이 매장에 들어와서 가장 먼저 방문하는 구역은 어디야?"

AI가 수행하는 작업:

search_widgets → "첫 방문", "여정", "체험" 관련 위젯 검색
get_widget_data → 첫 방문 구역 데이터 조회
구역별 첫 방문 빈도 분석

결과물 예시:

## 고객 첫 방문 구역 분석

고객이 매장 입장 후 **60초 이상 체류한 첫 번째 구역**:

| 순위 | 구역 | 첫 방문객 수 |
|------|------|-------------|
| 1 | 2층 A/S센터 | 342명 |
| 2 | 1층 메인홀 | 275명 |
| 3 | 2층 신상품존 | 215명 |
| 4 | 2층 액세서리존 | 185명 |
| 5 | 2층 키오스크 | 153명 |

**인사이트**: A/S센터 구역이 첫 방문지로 가장 많이 선택되며,
이는 A/S 목적 방문 고객 비중이 높음을 시사합니다.

프롬프트 작성 팁

효과적인 프롬프트 패턴

패턴	예시
리포트 생성	"OO매장 지난주 리포트 만들어줘"
비교 분석	"A구역과 B구역 성과 비교해줘"
트렌드 분석	"이번 달 방문객 추이 분석해줘"
순위 조회	"체류시간 긴 구역 TOP 5 알려줘"
특정 지표	"상담 전환율이 어떻게 돼?"

기간 지정 방법

"저번주" → 최근 7일
"이번 달" → 현재 월 1일~오늘
"2월" → 2025-02-01 ~ 2025-02-28
"최근 30일" → 오늘 기준 30일 전~오늘

접근 권한

MCP 서버는 기존 mAsh의 멀티테넌시 접근 제어를 그대로 적용합니다:

보드 레벨: 사용자가 속한 그룹에 연결된 보드만 접근 가능
대시보드 레벨: 소유자이거나 공개/읽기전용 대시보드만 접근 가능

권한이 없는 보드나 대시보드에 접근하면 "Access denied" 에러가 반환됩니다.

Tool 상세 스펙

list_boards

접근 가능한 보드 목록을 조회합니다. 다른 tool을 사용하기 전에 먼저 호출하여 보드 UID를 확인하세요.

파라미터: 없음

응답 예시:

{
  "boards": [
    {
      "uid": "28cb3371-7ddf-...",
      "name": "My Store"
    },
    {
      "uid": "4b2702e7-354f-...",
      "name": "My Company"
    }
  ],
  "count": 2
}

list_dashboards

보드의 대시보드 목록을 조회합니다.

파라미터:

파라미터	타입	필수	설명
`board_uid`	string	✅	보드 UID (`list_boards`에서 확인)

응답 예시:

{
  "dashboards": [
    {
      "uid": "abc123...",
      "name": "일일 리포트",
      "description": "매장 일일 현황",
      "permission": 1
    }
  ],
  "count": 1
}

get_dashboard

대시보드 상세 정보를 조회합니다.

파라미터:

파라미터	타입	필수	설명
`dashboard_uid`	string	✅	대시보드 UID

응답 예시:

{
  "uid": "abc123...",
  "name": "일일 리포트",
  "widgets": [
    {
      "uid": "widget1...",
      "name": "방문자 수",
      "tag": "visitor"
    }
  ],
  "widget_count": 5
}

get_widget_data

위젯 데이터를 조회합니다.

파라미터:

파라미터	타입	필수	설명
`dashboard_uid`	string	✅	대시보드 UID
`widget_uid`	string	✅	위젯 UID
`start_date`	string	✅	시작일 (YYYY-MM-DD)
`end_date`	string	✅	종료일 (YYYY-MM-DD)
`output_type`	string		출력 형식 (JSON, FORMATTED_JSON, RAW_JSON)

search_widgets

위젯을 검색합니다.

파라미터:

파라미터	타입	필수	설명
`board_uid`	string	✅	보드 UID
`name_contains`	string		위젯 이름 필터
`favorite_only`	boolean		즐겨찾기만 조회

list_widgets

대시보드의 모든 위젯을 조회합니다.

파라미터:

파라미터	타입	필수	설명
`dashboard_uid`	string	✅	대시보드 UID

문제 해결

"Authentication required" 에러

.mcp.json 파일이 프로젝트 루트에 있는지 확인하세요.
API Key가 올바르게 설정되었는지 확인하세요.

"Access denied" 에러

list_boards로 접근 가능한 보드를 먼저 확인하세요.
다른 사용자의 보드에는 접근할 수 없습니다.

MCP 서버가 목록에 없음

Claude Code를 재시작해보세요.
.mcp.json 파일의 JSON 형식이 올바른지 확인하세요.

MCP란?​

주요 장점​

제공 Tools​

설정 방법​

사전 준비: API Key 발급​

1. 환경변수 설정​

2. .mcp.json 파일 생성​

3. AI 도구 재시작​

지원 도구​

사용 예시​

기본 사용법​

보드 목록 조회​

대시보드 목록 조회​

위젯 데이터 분석​

위젯 검색​

실전 유스케이스​

유스케이스 1: 주간 데이터 리포트 생성​

유스케이스 2: 구역별 체류 시간 분석​

유스케이스 3: 교차 방문 분석​

유스케이스 4: 품목별 성과 비교​

유스케이스 5: 특정 기간 트렌드 분석​

유스케이스 6: 고객 여정 분석​

프롬프트 작성 팁​

효과적인 프롬프트 패턴​

기간 지정 방법​

접근 권한​

Tool 상세 스펙​

list_boards​

list_dashboards​

get_dashboard​

get_widget_data​

search_widgets​

list_widgets​

문제 해결​

"Authentication required" 에러​

"Access denied" 에러​

MCP 서버가 목록에 없음​

관련 문서​

MCP란?

주요 장점

제공 Tools

설정 방법

사전 준비: API Key 발급

1. 환경변수 설정

2. `.mcp.json` 파일 생성

3. AI 도구 재시작

지원 도구

사용 예시

기본 사용법

보드 목록 조회

대시보드 목록 조회

위젯 데이터 분석

위젯 검색

실전 유스케이스

유스케이스 1: 주간 데이터 리포트 생성

유스케이스 2: 구역별 체류 시간 분석

유스케이스 3: 교차 방문 분석

유스케이스 4: 품목별 성과 비교

유스케이스 5: 특정 기간 트렌드 분석

유스케이스 6: 고객 여정 분석

프롬프트 작성 팁

효과적인 프롬프트 패턴

기간 지정 방법

접근 권한

Tool 상세 스펙

list_boards

list_dashboards

get_dashboard

get_widget_data

search_widgets

list_widgets

문제 해결

"Authentication required" 에러

"Access denied" 에러

MCP 서버가 목록에 없음

관련 문서