MCP 서버

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

https://api.crisphive.com/mcp

먼저 이것부터 해보세요

연결한 뒤(chsk_test_ 샌드박스 키면 충분합니다) 아래 프롬프트를 에이전트에 그대로 붙여넣어 보세요 — 동일한 프롬프트가 모든 Crisphive 리스팅에 실려 있어 어디서든 똑같은 첫 실행 경험이 됩니다(프롬프트 자체는 영어로 유지됩니다):

• 작업 생성 — “Schedule a 2-hour HVAC job at 145 Laurier Ave W tomorrow for Marie Tremblay, 613-555-0142.” createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest
• 긴급 작업 삽입 — “Emergency plumbing job now at 99 Bank St for David Okafor (613-555-0198) — show me what gets rescheduled.” listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule
• 하루 일정 요약 — “Outline my day tomorrow and flag anything at risk.” listJobRequests → getTechnicianSchedule
• 가용 시간 찾기 — “Find 3 hours this week for a bike ride with my wife without risking any jobs.” getTechnicianSchedule → 에이전트가 일정의 여유를 스스로 추론합니다

같은 요청, 당신의 언어로

엔진은 누가 말하는지 신경 쓰지 않습니다 — 배차 담당자, 사장님, 개발자가 모두 같은 도구를 움직입니다. 같은 요청을 각 역할이 실제로 입력할 법한 말투로 정리했습니다(프롬프트 자체는 영어로 유지됩니다):

작동 방식

위의 모든 프롬프트는 같은 경로를 거칩니다. Claude가 자연어를 도구 호출로 변환하고, MCP 서버가 다른 모든 클라이언트와 동일한 공개 REST API를 구동하며, 결정론적 솔버가 일정을 계산합니다 — 최적화 코어에는 LLM이 전혀 없습니다. 결과는 비즈니스의 기록 시스템으로 동기화됩니다.

요구 사항

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_view)를 요청하세요. 생략하면 그 멤버가 할 수 있는 모든 것을 의미합니다. 액세스 토큰은 약 1시간 유효하므로 — 연결을 유지하려면 refresh 토큰을 사용하세요. 같은 토큰은 REST /v1 API에서도 동작합니다 — 멀티테넌트 연동 구축하기를 참고하세요.

연결 유효 기간

MCP 연결은 서로 독립적인 두 개의 시계로 관리됩니다. 매일 사용되는 에이전트는 일정에 따라 끊기는 일이 없고, 잊힌 에이전트는 스스로 만료됩니다.

• 유휴 기간 — 30일. 토큰을 갱신할 때마다 30일 동안 유효한 새 refresh 토큰이 발급됩니다. 연결을 계속 사용하면 무기한 연장되고, 30일 동안 사용하지 않으면 만료됩니다.
• 절대 상한 — 90일. 활동 여부와 관계없이 연결은 비즈니스 소유자가 승인한 시점으로부터 90일 후에 종료됩니다. 비즈니스는 Developers → MCP connections에서 연결별로 이 값을 1일부터 365일까지 설정할 수 있으며, 카운트다운은 변경 시점이 아니라 최초 승인 시점부터 계산됩니다.

두 시계 중 하나라도 다 되면 갱신이 실패하고 소유자가 동의 화면에서 앱을 다시 승인해야 합니다. 갱신 실패는 재시도 가능한 오류가 아니라 항상 "인가 플로우를 다시 시작하라"는 신호로 처리하세요. 연결이 만료되기 14일 전에 비즈니스의 소유자와 관리자에게 이메일이 발송됩니다 — 다시 승인하려면 소유자가 브라우저에서 작업해야 하므로, 키보다 더 일찍 경고가 발송됩니다.

도구

공개 /v1 API의 오퍼레이션당 하나씩 46개의 도구가 있으며, 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)을 반환하므로 — 헤더를 수정하고 다시 연결하세요. 유효 기간이 지난 키는 API_KEY_EXPIRED와 함께 401을 반환하므로 — 교체 키를 만드세요. 그랜트가 만료된 OAuth 연결은 OAUTH_GRANT_EXPIRED를 반환하므로 — 동의 화면에서 인가 플로우를 다시 실행하세요.

프로토콜 참고 사항

• 요청당 하나의 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 — 도구가 생성되는 기반이 되는 기계가 읽을 수 있는 스펙.