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 기반 인증, 본인 권한 범위 안의 데이터만 노출
• 멀티테넌시: 사용자별 접근 권한 자동 적용

제공 Tools

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

설정 방법

연결 방법은 두 가지입니다.

• 방법 1 — 브라우저 로그인 (OAuth): .mcp.json에 URL만 적으면, 첫 연결 시 브라우저가 열려 mAsh 로그인 → 승인하면 자동으로 연결됩니다. API Key를 직접 발급·복사할 필요가 없습니다. 권장.
• 방법 2 — API Key 직접 입력: 대시보드에서 발급한 API Key를 환경변수/.mcp.json에 직접 넣습니다. CI 등 브라우저가 없는 환경에 적합합니다.

두 방법 모두 본인 계정 권한 범위 안의 데이터만 노출됩니다. (방법 1 OAuth 는 mcp:dashboard:read scope 키를 발급하고, 방법 2 는 발급 시 scope 를 직접 선택합니다.)

방법 1: 브라우저 로그인 (OAuth)

Claude Code, Cursor, Claude Desktop 등 OAuth를 지원하는 MCP 클라이언트에서 사용합니다.

1. .mcp.json 파일 생성 (키 없이)

{
  "mcpServers": {
    "mash-api": {
      "type": "http",
      "url": "https://api.mash-board.io/mcp/"
    }
  }
}

Claude Code는 명령으로 추가할 수도 있습니다.

claude mcp add --transport http mash-api https://api.mash-board.io/mcp/

2. 첫 연결 — 브라우저 인증

AI 도구를 재시작(또는 첫 호출)하면 브라우저가 열립니다.

1. mAsh 로그인 — 이미 매쉬보드에 로그인되어 있으면 이 단계는 건너뜁니다.
2. 승인 화면 — "<도구 이름> 가 mAsh 계정에 접근하려고 합니다" → 허용되는 권한을 확인하고 승인.
3. 도구로 돌아오면 연결이 완료됩니다.

발급된 토큰은 약 90일 후 만료되며, 만료되면 같은 브라우저 인증을 한 번 더 거치면 됩니다.

토큰 폐기

브라우저 인증으로 발급된 토큰은 매쉬보드 개인 설정 → API 키 목록에 mcp-oauth: 로 시작하는 이름으로 나타납니다. 해당 카드의 삭제 버튼으로 언제든 폐기할 수 있습니다.

온프레미스 배포에서는 브라우저 인증 대신 방법 2를 사용하세요.

방법 2: API Key 직접 입력

사전 준비: API Key 발급

mAsh 대시보드의 개인 설정 화면에서 본인 계정으로 API Key를 발급받을 수 있습니다.

발급 시 선택 항목:

항목	설명
이름	키를 구분할 자유 텍스트 (예: "claude-code-laptop")
권한 (scope)	이 키가 접근 가능한 범위 — <surface>:<resource>:<action> 또는 *. 예: mcp:dashboard:read(MCP 대시보드 조회 도구), mcp:*(MCP 전체), api:*(REST 전체), *(전체). 비우면 *. MCP 연동만 할 거면 mcp:dashboard:read 권장.
만료 기간	7 / 30 / 90 / 180일 / 무기한 중 선택

발급된 키는 1회만 표시되며 창을 닫으면 다시 확인할 수 없습니다. 안전한 곳에 보관하세요.

만료 관리: 무기한 키도 발급 가능하지만 운영 보안을 위해 30~180일 만료를 권장합니다. 만료된 키는 카드에 "만료됨" 라벨이 표시되고 호출 시 거부됩니다.

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: 방법 1(OAuth) 사용 시 첫 연결에서 브라우저 인증 창이 열립니다. 방법 2(API Key) 사용 시에도 서버 승인 팝업이 표시될 수 있습니다.
• Cursor / Claude Desktop: 동일한 .mcp.json 설정을 사용합니다. OAuth 지원 버전에서는 방법 1이 동작합니다.

사용 예시

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

기본 사용법

보드 목록 조회

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

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

대시보드 목록 조회

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

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

위젯 데이터 분석

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

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

위젯 검색

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

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

---

실전 유스케이스

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

프롬프트 예시:

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

AI가 수행하는 작업:

1. list_boards → "OO스토어" 보드 UID 확인
2. list_dashboards → 해당 보드의 대시보드 목록 조회
3. list_widgets → 대시보드 내 위젯 목록 파악
4. 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가 수행하는 작업:

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

결과물 예시:

## 체류 시간 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가 수행하는 작업:

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

결과물 예시:

## 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가 수행하는 작업:

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

결과물 예시:

## 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가 수행하는 작업:

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

결과물 예시:

## 월간 방문객 트렌드

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

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

---

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

프롬프트 예시:

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

AI가 수행하는 작업:

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

결과물 예시:

## 고객 첫 방문 구역 분석

고객이 매장 입장 후 **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일 전~오늘

접근 권한

발급한 API Key 로 다음 tool 들을 호출할 수 있습니다.

호출 가능 Tool	설명
list_boards	접근 가능한 보드 목록
list_dashboards	보드의 대시보드 목록
get_dashboard	대시보드 상세 + 위젯 목록
list_widgets	대시보드의 위젯 목록
search_widgets	위젯 검색
get_widget_data	위젯 데이터 (기간 지정)

이 외의 tool 호출 시 -32002 Forbidden 응답이 반환됩니다.

데이터 접근 범위

위 tool 들도 본인 권한 범위 안에서만 동작합니다.

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

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

Rate Limit

API Key 단위로 호출 한도가 적용됩니다.

윈도우	기본 한도
10초	30회
일	3,000회

한도 초과 시 일정 시간 호출이 차단됩니다. 일반적인 분석/리포트 자동화에는 충분한 한도이며, 대량 호출이 필요한 경우 조직 관리자에게 문의하세요.

사용량 확인

mAsh 대시보드의 개인 설정 화면의 API 키 섹션에서 본인이 발급한 키의 사용량을 확인할 수 있습니다.

각 키 카드에:

• 최근 7일 N회 — 최근 호출 횟수
• 마지막 사용 — 가장 최근 호출 시각
• 만료 — 만료일 또는 "무기한"

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" 에러

• 방법 1(OAuth): 인증 토큰이 없거나 만료되면 서버가 401을 응답하며, OAuth 지원 클라이언트는 자동으로 브라우저 인증을 다시 띄웁니다. 브라우저 창이 뜨지 않으면 도구를 재시작하거나, MCP 클라이언트가 OAuth(http transport remote 서버)를 지원하는 버전인지 확인하세요. 그래도 안 되면 방법 2로 전환하세요.
• 방법 2(API Key): .mcp.json 파일이 프로젝트 루트에 있는지, API Key 가 올바르게 설정됐는지, 키가 만료되지 않았는지 확인하세요 (대시보드 키 카드에 "만료됨" 라벨이 보이면 새 키 발급).
• 단시간 다수 호출 시 rate limit 에 걸린 경우 잠시 후 재시도하세요.

"Forbidden" 에러

• 위 접근 권한 에 명시되지 않은 tool 호출이거나 데이터 접근 권한 범위를 벗어난 경우입니다.
• list_boards 로 접근 가능한 보드를 먼저 확인하세요.

"Access denied" 에러

• 다른 사용자의 보드/대시보드에는 접근할 수 없습니다.
• 본인이 속한 그룹과 보드 연결이 올바른지 조직 관리자에게 확인하세요.

MCP 서버가 목록에 없음

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

관련 문서

• API 인증 가이드
• 대시보드 API 소개
• MCP 공식 문서