MCP 연결

MCP란?

MCP(Model Context Protocol)는 AI 에이전트가 외부 도구와 상호작용하기 위한 표준 프로토콜입니다. 슈츠 MCP 서버를 연결하면:

• AI와 대화하면서 슈츠 데이터를 조회하고 수정
• 블록, 데이터모델, 워크플로우 등 50개 도구 사용 가능
• 별도 코드 작성 없이 자연어로 슈츠 조작

인증 방식

슈츠 MCP 서버는 공식 프로토콜에 따라 OAuth 2.1 인증을 사용합니다. 워크스페이스별로 고유한 MCP URL을 통해 연결합니다.

설정 방법

{
  "mcpServers": {
    "suits": {
      "type": "http",
      "url": "https://suits.work/api/mcp/{workspaceId}"
    }
  }
}

{workspaceId}는 워크스페이스 설정에서 확인할 수 있습니다.

연결 과정

1. 첫 연결 시 브라우저를 통해 슈츠 계정으로 로그인 화면이 열림
2. 로그인 완료 후 자동으로 연결됨
3. OAuth 사용자가 해당 워크스페이스의 멤버인지 검증됨
4. 모든 작업이 실제 로그인한 사용자로 기록됨

사전 준비

1단계: 워크스페이스 ID 확인

1. 워크스페이스 사이드바 하단의 설정 (톱니바퀴 아이콘) 클릭
2. 설정 모달에서 API 키 탭 선택
3. 상단의 MCP 연결 URL 섹션에서 전체 URL 확인 및 복사

2단계: 서버 URL 구성

https://suits.work/api/mcp/{workspaceId}

예시:

https://suits.work/api/mcp/d5e7d4fa-781e-4d02-a262-6761a4a0f877

Claude Desktop 연결

Claude Desktop 설정 파일을 수정하여 슈츠 MCP 서버를 추가합니다.

macOS

설정 파일 위치: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "suits": {
      "type": "http",
      "url": "https://suits.work/api/mcp/{workspaceId}"
    }
  }
}

Windows

설정 파일 위치: %APPDATA%\Claude\claude_desktop_config.json

동일한 JSON 구조를 사용합니다.

연결 확인

Claude Desktop을 재시작한 후, 대화창에서 다음과 같이 물어보세요:

"슈츠에서 데이터모델 목록을 보여줘"

Claude Code 연결

Claude Code의 MCP 설정 파일을 수정합니다.

설정 방법

프로젝트 루트의 .mcp.json 또는 CLI 명령어로 설정:

{
  "mcpServers": {
    "suits": {
      "type": "http",
      "url": "https://suits.work/api/mcp/{workspaceId}"
    }
  }
}

또는 CLI로 추가:

claude mcp add --transport http suits https://suits.work/api/mcp/{workspaceId}

연결 확인

Claude Code에서 /mcp 명령어를 실행하여 연결 상태를 확인합니다:

suits: https://suits.work/api/mcp/... (HTTP) - ✓ Connected

처음 연결 시 브라우저에서 Google 로그인 창이 열립니다.

Cursor 연결

Cursor 설정에서 MCP 서버를 추가합니다.

설정 파일

~/.cursor/mcp.json:

{
  "servers": {
    "suits": {
      "type": "http",
      "url": "https://suits.work/api/mcp/{workspaceId}"
    }
  }
}

Windsurf 연결

Windsurf IDE에서 MCP 서버를 설정합니다.

설정 파일

.windsurf/mcp.json:

{
  "mcpServers": {
    "suits": {
      "url": "https://suits.work/api/mcp/{workspaceId}"
    }
  }
}

여러 워크스페이스 동시 연결

여러 워크스페이스에서 동시에 작업하려면 각각 별도의 MCP 서버로 등록합니다.

설정 예시

{
  "mcpServers": {
    "suits-marketing": {
      "type": "http",
      "url": "https://suits.work/api/mcp/marketing-workspace-id"
    },
    "suits-dev": {
      "type": "http",
      "url": "https://suits.work/api/mcp/dev-workspace-id"
    },
    "suits-personal": {
      "type": "http",
      "url": "https://suits.work/api/mcp/personal-workspace-id"
    }
  }
}

사용 방법

AI에게 어떤 워크스페이스에서 작업할지 명시하면 됩니다:

"마케팅팀 워크스페이스에서 캠페인 데이터모델 목록 보여줘"

"개발팀 워크스페이스에 버그 트래커 페이지 만들어줘"

Claude가 맥락에 따라 적절한 워크스페이스의 도구를 선택합니다.

사용 가능한 도구

문제 해결

인증 오류 (401)

OAuth authentication required

확인사항:

• OAuth 로그인이 완료되었는지 확인
• 브라우저에서 Google 로그인 팝업이 차단되지 않았는지 확인
• URL에 올바른 workspaceId가 포함되어 있는지 확인

권한 오류 (403)

You are not a member of this workspace. Please login with an account that has access.

확인사항:

• 로그인한 계정이 해당 워크스페이스의 멤버인지 확인
• 다른 계정으로 로그인되어 있을 수 있음 (Google 또는 이메일)
• 워크스페이스 설정에서 멤버 초대 필요

속도 제한 (429)

Too many requests

확인사항:

• 요청 빈도 줄이기
• Retry-After 헤더 확인 후 재시도

연결 안됨

확인사항:

• 설정 파일 JSON 문법 오류 여부
• AI 도구 재시작 필요
• 인터넷 연결 상태
• URL의 workspaceId가 올바른지 확인

OAuth 로그인 창이 안 뜨는 경우

확인사항:

• 브라우저 팝업이 차단되어 있지 않은지 확인
• Claude Code에서는 터미널에 표시되는 URL을 직접 복사하여 브라우저에서 열 수 있음

기술 사양

프로토콜

엔드포인트

OAuth Discovery 엔드포인트

OAuth 엔드포인트

필수 헤더

Authorization: Bearer mcp_xxx...  (OAuth 토큰 - MCP 클라이언트가 자동 관리)
Content-Type: application/json

다음 단계

• Taylor AI 도구 - 50개 도구 상세 설명
• 인증 - API 키 발급 및 관리
• 데이터모델 API - REST API로 데이터 조작