Crisphive MCP

Crisphive API의 공식 MCP(Model Context Protocol) 서버입니다 — 현장 서비스를 위한 에이전트형 AI 스케줄링 인프라입니다.

AI 에이전트 — Claude, ChatGPT, Gemini, Cursor 또는 모든 MCP 클라이언트 — 가 위치, 기술, 실시간 가용성을 기준으로 고객과 업체 간 일정을 매칭하고, 작업에 인력을 배치할 수 있게 해 줍니다: 작업 예약 및 약속 스케줄링, 작업 지시(work-order) 추적, 실시간 디스패치 및 스케줄링 엔진의 가용성, 고객(CRM) 동기화, 서비스 카탈로그, 기술자 및 크루 명단, 지리적 서비스 영역과 차량(플릿) — HVAC, 배관, 전기, 청소, 가전 수리, 부동산 유지보수 등의 기술 트레이드 및 가정 서비스를 위한 것입니다. 호스팅되는 원격 서버로, 별도 설치나 실행이 필요하지 않습니다(이 저장소에는 문서와 레지스트리 매니페스트가 들어 있습니다).

https://api.crisphive.com/mcp

먼저 이 프롬프트들을 시도해 보세요

연결만 하면(chsk_test_ 샌드박스 키로 충분합니다), 아래 프롬프트를 그대로 에이전트에 붙여넣어 보세요:

1. 작업 생성 — "내일 145 Laurier Ave W에서 Marie Tremblay 고객(613-555-0142)에게 2시간짜리 HVAC 작업을 예약해 줘." (createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest)

2. 긴급 삽입 — "지금 99 Bank St에서 David Okafor 고객(613-555-0198)에게 긴급 배관 작업을 잡아 줘 — 무엇이 재스케줄링되는지 보여 줘." (listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule)

3. 일일 개요 — "내일 일정을 개요로 보여 주고 위험한 부분을 표시해 줘." (listJobRequests → getTechnicianSchedule)

4. 가용성 탐색 — "어떤 작업도 위험에 빠뜨리지 않고 아내와 자전거를 탈 3시간을 찾아 줘." (getTechnicianSchedule → 에이전트가 여유 공간(slack)을 기준으로 추론)

동일한 프롬프트가 모든 Crisphive 목록 및 문서 페이지에 표시되므로, 이곳에서 보는 것이 어디서나 동일한 최초 실행 경험입니다.

Related MCP server: Servicialo

요구 사항

Streamable HTTP로 원격 서버를 지원하는 모든 MCP 클라이언트 — claude.ai, Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, LM Studio, ….

설치

claude.ai / Claude Desktop (OAuth — 키 불필요)

**설정(Settings) → 커넥터(Connectors) → 사용자 지정 커넥터 추가(Add custom connector)**에서 https://api.crisphive.com/mcp를 붙여넣으세요. 동의 화면이 열리면 Crisphive 비즈니스 소유자로 로그인하세요. (사용자 지정 커넥터는 이를 지원하는 Claude 요금제가 필요합니다.)

Claude Code

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

# or with an API key (sandbox key shown — safe to experiment)
claude mcp add --transport http crisphive https://api.crisphive.com/mcp \
  --header "Authorization: Bearer chsk_test_YOUR_KEY"

Cursor

또는 .cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "crisphive": { "url": "https://api.crisphive.com/mcp" }
  }
}

VS Code

code --add-mcp '{"name":"crisphive","url":"https://api.crisphive.com/mcp"}'

ChatGPT

설정(Settings) → 커넥터(Connectors)(개발자 모드) → URL https://api.crisphive.com/mcp(OAuth)로 MCP 서버를 추가하세요.

Gemini CLI

~/.gemini/settings.json에 추가하세요 (참고: Gemini CLI는 Streamable HTTP 서버에 httpUrl을 사용합니다):

{
  "mcpServers": {
    "crisphive": {
      "httpUrl": "https://api.crisphive.com/mcp",
      "headers": { "Authorization": "Bearer chsk_test_YOUR_KEY" }
    }
  }
}

기타 MCP 클라이언트 (Windsurf, Cline, Zed, LM Studio, …)

대부분의 클라이언트는 표준 원격 서버 형식을 동일하게 사용합니다:

{
  "mcpServers": {
    "crisphive": {
      "url": "https://api.crisphive.com/mcp",
      "headers": { "Authorization": "Bearer chsk_test_YOUR_KEY" }
    }
  }
}

일부 클라이언트에서 URL 필드명만 다를 뿐입니다:

stdio만 지원하는 클라이언트는 mcp-remote로 브리지할 수 있습니다:

{
  "mcpServers": {
    "crisphive": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.crisphive.com/mcp"]
    }
  }
}

로컬 서버 (npm — @crisphive/mcp)

이 저장소는 경량 로컬 stdio 서버도 제공합니다. 호스팅 엔드포인트와 동일한 /v1 OpenAPI 스펙에서 생성된 동일한 43개 도구(동일한 이름, 동일한 스키마)이며, 각 호출은 키와 함께 Crisphive API로의 HTTPS 요청입니다. 비즈니스 로직은 로컬에서 실행되지 않습니다.

{
  "mcpServers": {
    "crisphive": {
      "command": "npx",
      "args": ["-y", "@crisphive/mcp"],
      "env": { "CRISPHIVE_API_KEY": "chsk_test_YOUR_KEY" }
    }
  }
}

환경 변수:

클라이언트가 지원한다면 호스팅 원격 서버(https://api.crisphive.com/mcp)를 선호하세요 — OAuth, 키 처리 불필요, 항상 최신 상태입니다. 로컬 패키지는 stdio 전용 클라이언트와 자체 호스팅 구성에 필요합니다.

이 저장소에서 개발할 때: npm ci && npm test. 도구 레지스트리(src/tools.generated.json)는 생성되는 파일입니다 — npm run generate로 라이브 스펙에서 갱신되고, /v1과 어긋나면 CI가 실패합니다.

인증

모든 요청은 베어러 토큰으로 전송되는 비밀 API 키로 인증됩니다. 키는 Crisphive 비즈니스 관리자 대시보드에서 생성하세요. 키 접두사가 데이터 환경을 결정합니다:

• chsk_live_… → 라이브(운영) 데이터

• chsk_test_… → 샌드박스(격리 테스트) 데이터

키는 환경 변수에서 로드하세요 — 절대 커밋하지 마세요.

키는 만료됩니다. 키 수명은 생성 시 선택되며 — 기본 30일, 최대 365일 — 해당 키의 수명 동안 고정되고 이후 연장할 수 없습니다. 갱신하려면 두 번째 키를 만들고, 에이전트가 그 키를 가리키고, 그런 다음 첫 번째 키를 해지하면 됩니다. 하나의 업체에서 여러 활성 키를 동시에 보유할 수 있으므로 교체 중에도 다운 없고 특별한 엔드포인트가 필요하지 않습니다(AWS가 액세스 키에 적용하는 것과 같은 절차). 대시보드나 키 API에서 expires_at을 확인하고 교체를 예약하세요. 수명이 다한 키는 API_KEY_INVALID와 구분되는 API_KEY_EXPIRED 오류를 반환하므로, 갱신 누락과 키 취소를 별도로 알림할 수 있습니다.

Crisphive는 키가 만료되기 7일 전(OAuth 연결은 14일 전)에 업주에게 이메일을 보내므로 만료는 뜻하지 않은 일이지만 — 이메일이 업체로 가며 반드시 여러분에게 가는 것은 아니므로, expires_at을 직접 추적하세요. 7일 미만용으로 의도적으로 생성한 키는 사전 안내가 없습니다. 생성 시기에 이미 만료가 도착했기 때문입니다.

MCP 엔드포인트는 최종 사용자 커넥터(claude.ai, ChatGPT, …)에 대해 OAuth 2.1도 지원합니다. 업체 소유자가 동의 화면에서 에이전트를 승인하며, 키를 직접 다룰 필요가 없습니다. 이를 준수하는 MCP 클라이언트는 디스커버리, 동적 클라이언트 등록, 인가 코드 + PKCE가 포함된 전체 흐름을 자동 실행합니다. 전체 흐름, 스코프, 토큰 수명: docs/integration.md.

도구

공개 /v1 API의 각 조작에 대해 하나씩 총 43개 도구 — SDK 메서드(listCustomers, createJobRequest, …)와 동일한 이름으로, 같은 OpenAPI 스펙에서 생성되어 REST와 MCP가 어긋나지 않습니다. 전체 레퍼런스: docs/tools.md.

일반적인 에이전트 흐름:

listSkills / listJobTypes                → discover reference IDs
createCustomer                           → { customer_id }
listJobRequestBookingWindows             → offer only the returned windows
createJobRequest                         → booking created
quoteJobRequest → confirmJobRequest      → scheduled (auto or forced technician)
getJobRequest / listJobRequestChanges    → track status

긴급(P0) 흐름:

createJobRequest (priority: "p0") → quoteJobRequest
listEmergencyCandidates                  → ranked techs + crew_recommendation
previewEmergencyReschedule               → what moves (or reassigns)
commitEmergencyReschedule                → inserted + auto-confirmed

페이지네이션

목록 도구는 page / limit을 받고 meta 객체(total, count, per_page, current_page, total_pages)를 반환합니다.

멱등성

생성/커밋 도구들(createCustomer, createTechnician, createJobRequest, confirmJobRequest, commitJobRequestMove, commitEmergencyReschedule)은 idempotency_key 인자를 받아, 재시도하더라도 중복이 발생하지 않게 합니다 — 재시도하는 경우 같은 값을 전달하세요.

오류

모든 도구는 Crisphive 응답 봉투를 텍스트 및 structuredContent로 반환합니다: error_code는 성공 시 0, 실패 시 안정적인 문자열(CUSTOMER_NOT_FOUND, API_KEY_INVALID, …)입니다. 메시지 문자열이 아닌 코드로 매칭하세요.

문서

• 문서: https://docs.crisphive.com

• MCP: https://docs.crisphive.com/mcp

• API 레퍼런스: https://docs.crisphive.com/technical-reference

• 웹훅: https://docs.crisphive.com/webhook

• AI를 위한 것(OpenAPI 스펙 + 어시스턴트 부트스트랩): https://docs.crisphive.com/for-ai

• 클라이언트 통합 가이드: docs/integration.md

• 도구 레퍼런스: docs/tools.md

개인정보 및 지원

• 개인정보 처리방침: https://crisphive.com/privacy-policy — Crisphive는 API를 통해 접근 가능한 비즈니스 데이터(고객, 예약, 기술자, 차량)를 서비스 운영 목적으로만 처리하며, 개인정보를 판매하지 않습니다. 데이터는 계정이 활성화되어 있는 동안 보관되며, 필요한 경우에만 서비스 제공자/하위 처리자와 공유됩니다. MCP를 통해 연결된 에이전트는 권한을 부여한 비즈니스를 대신하여 행동하며, 해당 비즈니스의 데이터, 환경(라이브 vs 샌드박스) 및 부여된 권한 범위로 제한됩니다.

• 지원: support@crisphive.com

라이선스

MIT