MCP 서버

CrispHive의 공식 MCP 서버입니다. Claude, ChatGPT, Cursor 또는 모든 MCP 클라이언트를 CrispHive에 연결하면, 필드 서비스 비즈니스를 위해 고객을 관리하고, 서비스 카탈로그를 탐색하며, 실시간 예약 가용성을 확인하고, 작업을 예약할 수 있습니다 — Developer API의 모든 REST 엔드포인트가 도구로 노출됩니다.

https://api.crisphive.com/mcp

요구 사항

Streamable HTTP로 원격 서버와 통신하고 커스텀 헤더를 보낼 수 있는 모든 MCP 클라이언트 — claude.ai, Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, LM Studio 등. 트랜스포트는 상태를 유지하지 않으며(순수 JSON 응답 — SSE도 세션도 없음), 서버는 도구만 노출합니다.

설치

아래에서 사용하는 클라이언트를 선택하면 연결 방법을 정확히 확인할 수 있습니다:

# OAuth — you'll be prompted to authorize in the browser
claude mcp add --transport http crisphive https://api.crisphive.com/mcp

# …or pass an API key to skip the browser step
claude mcp add --transport http crisphive https://api.crisphive.com/mcp \
  --header "Authorization: Bearer chsk_test_YOUR_KEY"

인증

요청은 베어러 토큰으로 전송되는 시크릿 API 키로 인증되며, REST /v1 API와 동일한 키를 사용합니다. 키는 CrispHive 비즈니스 대시보드에서 생성합니다. 키 프리픽스가 에이전트가 다루는 데이터를 결정합니다:

• chsk_live_… → 라이브(프로덕션) 데이터.
• chsk_test_… → 샌드박스(격리된 테스트) 데이터. 테스트 키를 가진 에이전트는 오직 샌드박스 데이터만 다룰 수 있으므로, 에이전트에게 실험을 맡기는 가장 권장되는 방법입니다.

키는 서버 사이드에 보관하고 환경 변수에서 불러오세요 — 절대 커밋하거나 클라이언트 사이드 앱에 chsk_ 키를 담아 배포하지 마세요.

OAuth 2.1 (API 키 불필요)

claude.ai / ChatGPT 커넥터 — 또는 사용자가 각자의 CrispHive 비즈니스를 가져오는 제품 — 을 만들고 계신가요? /mcp 엔드포인트는 완전한 OAuth 2.1 인증 서버이기도 합니다: 비즈니스 소유자가 동의 화면에서 에이전트를 승인하며 키를 복사할 필요가 전혀 없습니다. 규격을 준수하는 MCP 클라이언트는 전체 플로우를 자동으로 실행하며(일반적으로 OAuth 코드를 직접 작성할 필요가 없습니다), WWW-Authenticate: Bearer resource_metadata="…"를 담은 401에 의해 트리거됩니다:

이후에는 Authorization: Bearer <access_token>로 /mcp를 호출하며 — API 키 방식과 동일합니다. 토큰은 동의한 소유자의 비즈니스, 리전, 환경에 바인딩되므로 에이전트는 절대 다른 테넌트에 접근하거나 라이브↔샌드박스를 전환할 수 없습니다. 에이전트를 제한하려면 더 좁은 scope(공백으로 구분된 권한 코드, 예: customers_view job_requests_view)를 요청하고, 전체 비즈니스 접근이 필요하면 생략하세요. 액세스 토큰은 약 1시간 유효하므로 — 연결을 유지하려면 refresh 토큰을 사용하세요.

도구

공개 /v1 API의 오퍼레이션당 하나씩 22개의 도구가 있으며, SDK 메서드와 이름이 동일합니다(listCustomers, createJobRequest 등). 동일한 OpenAPI 스펙에서 생성되므로 REST와 MCP가 절대 어긋나지 않습니다. 경로/쿼리 파라미터와 요청 본문 필드는 도구마다 하나의 인자 객체로 병합됩니다.

• 모든 도구는 원본 REST 엔벨로프 — { error_code, message, data } — 를 텍스트로 반환합니다. 에이전트는 성공 시 data를 꺼내고 실패 시 error_code를 읽습니다.
• 제한된 키는 그대로 적용됩니다: customers_view로 스코프가 제한된 키는 쓰기 도구에서 403을 받습니다.
• 생성 도구(createCustomer, createJobRequest)는 선택적 idempotency_key를 받아 Idempotency-Key 헤더로 전달합니다 — 재시도 시 동일한 값을 전달하면 재시도가 중복을 만들지 않습니다.
• 헤더 입력도 인자입니다: 예를 들어 listJobRequestBookingWindows는 x_timezone(IANA 시간대, X-Timezone 헤더로 전송)을 받습니다.
• 모든 도구는 outputSchema를 선언하고 텍스트와 함께 structuredContent(파싱된 엔벨로프)를 반환하므로, 타입이 지정된 클라이언트는 재파싱을 생략할 수 있습니다.
• 동작 힌트가 도구별로 설정됩니다 — 읽기에는 readOnlyHint가, 삭제에는 destructiveHint가 붙으므로, Claude 같은 클라이언트가 파괴적 작업을 실행하기 전에 확인을 요청할 수 있습니다.

일반적인 에이전트 플로우는 다음과 같습니다:

listSkills / listJobTypes                → discover reference IDs
createCustomer                           → { customer_id }
listJobRequestBookingWindows             → offer only the returned windows
createJobRequest                         → booking created
getJobRequest / listJobRequestChanges    → track status

페이지네이션

목록 도구는 page / limit을 받아 meta 객체(per_page, current_page, total_pages)를 반환하므로, 에이전트가 대규모 결과 집합을 한 페이지씩 탐색할 수 있습니다.

요청 제한

요청은 키당 제한되며 REST와 공유됩니다: 분당 240건. 429 엔벨로프를 받으면 백오프한 뒤 재시도하세요.

오류

모든 도구는 CrispHive 응답 엔벨로프를 (텍스트와 structuredContent 형태로) 반환합니다: error_code는 성공 시 0이고, 실패 시에는 안정적인 문자열(CUSTOMER_NOT_FOUND, API_KEY_INVALID 등)이 담깁니다. 메시지 텍스트가 아니라 코드로 매칭하세요. 유효하지 않거나 폐기된 키는 HTTP 401(API_KEY_INVALID)을 반환하므로 — 헤더를 수정하고 다시 연결하세요.

프로토콜 참고 사항

• 요청당 하나의 JSON-RPC 2.0 메시지(또는 최대 20개의 배치)를 POST하세요. 응답은 application/json이며, 알림(notification)은 202로 확인 응답됩니다.
• 서버는 상태를 유지하지 않습니다 — 세션 ID가 발급되거나 요구되지 않으며, GET /mcp는 405를 반환합니다(서버 푸시 스트림 없음).
• UUID 경로 인자는 디스패치 전에 검증됩니다 — UUID가 아닌 ID는 다른 오퍼레이션이 아니라 인밴드(in-band) 도구 오류를 반환합니다.
• 허용되는 프로토콜 리비전: 2025-06-18, 2025-03-26, 2024-11-05.

문서

• 가이드 — 개념과 예약 플로우는 여기에서 시작하세요.
• API 레퍼런스 — 모든 엔드포인트, 인자, 스키마.
• For AI — OpenAPI 스펙과 바로 붙여 넣을 수 있는 어시스턴트 부트스트랩.
• openapi.json — 도구가 생성되는 기반이 되는 기계가 읽을 수 있는 스펙.