MCP 통합
모듈형 조직의 경우 연결된 조직에 활성 CRM 모듈과 통합에 필요한 스코프가 모두 있어야 합니다. CRM에 액세스할 수 없으면 기본 API가 module_not_active와 함께 HTTP 403을 반환합니다. 다시 시도하기 전에 Subscription에서 모듈 액세스 권한을 해결하세요. API 키만 변경해서는 이 오류가 해결되지 않습니다.
Scoutello는 조직 데이터에 대한 제어된 액세스를 위해 원격 Model Context Protocol(MCP) 서버를 제공합니다. 이 서버는 Scoutello REST API와 동일한 통합, API 키, 스코프, 테넌트 확인, 속도 제한 및 레코드 동작을 사용합니다.
AI 클라이언트 또는 에이전트가 Scoutello 작업을 도구로 검색하고 호출해야 하는 경우 MCP를 사용하세요. 애플리케이션에 일반적인 HTTP 엔드포인트 또는 생성된 OpenAPI 클라이언트가 필요한 경우 REST를 사용하세요. 두 인터페이스 모두 동일한 기본 데이터 계약을 사용합니다.
연결 전 준비
조직 관리자가 Organization settings → Developer/API에서 통합을 생성해야 합니다. 키를 생성하거나 교체할 때는 다음을 따르세요.
- MCP 클라이언트에 필요한 읽기 및 쓰기 스코프만 선택합니다.
- 표시될 때 전체
sctl_api_키를 저장합니다. Scoutello는 이 키를 한 번만 표시합니다. - 키를 소스 코드 저장소가 아닌 MCP 클라이언트의 보안 정보 또는 환경 설정에 저장합니다.
동일한 통합 키로 REST와 MCP를 모두 호출할 수 있습니다. MCP 전용 키를 별도로 생성할 필요는 없으며 권장되지도 않습니다. 이전 sctl_mcp_ 키는 허용되지 않습니다.
연결 값
다음 값으로 클라이언트를 구성합니다.
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
YOUR_API_KEY를 저장한 통합 키로 바꿉니다. 클라이언트별 구성 형식은 다르지만, 위의 전송 방식, URL 및 HTTP 헤더는 동일합니다. 클라이언트에서 Authorization를 설정할 수 없는 경우 대신 x-api-key에 키를 전송할 수 있습니다. 두 헤더를 모두 구성하지 마세요.
기존 https://admin.scoutello.com/api/mcp URL은 호환성을 위한 별칭으로 계속 제공됩니다. 새 연결에는 버전이 지정된 /api/v1/mcp 엔드포인트를 사용하세요.
연결 확인
클라이언트가 연결되면 먼저 whoami 도구를 호출합니다. 이 도구는 조직 레코드를 노출하지 않고 현재 통합 및 조직, 자격 증명 만료 및 사용 정보, 속도 제한 상태, 부여된 스코프를 반환합니다.
whoami에서 예상하지 않은 조직 또는 통합을 식별하면 다른 도구를 호출하기 전에 클라이언트 연결을 해제하고 키를 수정하세요.
도구 및 스코프
MCP 서버는 현재 키에 부여된 도구만 알립니다. 해당 읽기 스코프만으로는 쓰기 도구를 검색하거나 호출할 수 없습니다.
| API 스코프 | MCP 도구 |
|---|---|
contacts.read | contacts_list, contacts_get, contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list, tasks_get, tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list, protocols_get, protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list, opportunities_get, opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list, projects_get, projects_get_by_external_id |
projects.write | projects_batch_upsert (참여자 upsert 포함) |
milestones.read | milestones_list, milestones_get, milestones_get_by_external_id |
milestones.write | milestones_batch_upsert |
members.read | members_list |
events.read | events_list, events_get, events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list, mails_get |
mail-drafts.read | mail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id |
mail-drafts.write | mail_drafts_batch_upsert (사람의 검토 준비 전용) |
tags.read | tags_list |
whoami는 인증된 연결에서 항상 사용할 수 있습니다. 도구 입력 및 결과는 연결된 REST 작업과 동일한 스키마 및 응답 봉투를 따릅니다.
contacts_list는 이름(이름/성/회사명), type, status 및 tagIds(선택한 태그와 일치하는 1~50개의 ID 배열)에서 제한된 search를 허용합니다. 모든 검색 토큰은 이름 필드와 일치해야 하며, 모든 필터는 AND로 결합됩니다. 모든 커서 페이지에서 이 필터를 유지하세요. 예를 들어 { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] }는 전체 인벤토리를 조회하지 않고 일치하는 기존 계정을 찾습니다.
Scoutello 로그인에 연결된 비회원 CRM 연락처는 읽고 참조할 수 있지만, 멤버십/계정 필드는 숨겨지며 연락처 수정은 보호됩니다. 외부 링크만 사용하는 upsert로 externalId, 해당 scoutelloId 및 선택적 externalUpdatedAt를 사용하여 읽을 수 있는 연락처를 등록할 수 있습니다. 모든 CRM 필드는 생략하세요. 이후 재시도 또는 메타데이터 업데이트에서는 scoutelloId를 생략합니다. 연락처 경계 및 연결 규칙을 참조하세요.
안전한 쓰기 작업
배치 업서트 도구는 Scoutello 데이터를 즉시 변경할 수 있습니다. 동일한 통합과 외부 ID를 사용하면 멱등적으로 동작하지만, 변경 사항을 적용하기 전에 대상 리소스, 조직 및 범위를 다시 확인해야 합니다.
mode를 validate로 설정하면 기록하지 않고 일치 여부와 유효성 검사를 실행할 수 있습니다. 결과를 확인한 후 mode: "apply"로 다시 호출하여 유효한 레코드를 적용합니다. MCP는 삭제 작업을 제공하지 않습니다.
통합을 일시 중지하면 해당 키를 사용하는 REST 및 MCP 요청이 모두 거부됩니다. 키를 교체하면 인증 정보가 변경되고, 통합을 폐기하면 해당 통합에 속한 모든 인증 정보가 영구적으로 비활성화됩니다.
문제 해결
| 결과 | 확인할 사항 |
|---|---|
401 인증 오류 | 전체 키가 포함되어 있는지, 헤더가 Bearer를 사용하며 키를 따옴표로 감싸지 않았는지 확인합니다. |
403 권한 오류 | 통합 키를 교체하여 필요한 범위를 부여한 다음, 교체된 키로 클라이언트를 업데이트합니다. |
MCP URL에서 404 | URL이 /api/v1/mcp로 끝나는지 확인합니다. 해당 Scoutello 환경에서 MCP 서비스가 아직 활성화되지 않았을 수 있습니다. |
429 속도 제한 오류 | 다시 시도하기 전에 응답으로 반환된 재설정 시각까지 기다립니다. REST와 MCP는 동일한 통합 할당량을 사용합니다. |
| 도구가 없음 | whoami로 키의 범위를 확인합니다. 사용할 수 없는 도구는 검색 결과에서 의도적으로 제외됩니다. |
레코드 필드, 페이지 매김, 배치 동작 및 오류 형식은 Scoutello API 레퍼런스를 참조하세요.
연결된 프로젝트 계획
프로젝트를 만든 다음 안정적인 통합 외부 ID를 사용하여 마일스톤, 작업 및 프로토콜을 차례로 생성합니다. 새로운 마일스톤에 접근하려면 milestones.read/milestones.write가 필요하며, 할당 가능한 멤버를 조회하려면 members.read를 부여합니다. 기존 인증 정보의 권한 범위는 자동으로 확대되지 않습니다. 권한을 교체하거나 부여한 후 도구 검색을 새로 고치고 whoami를 확인합니다.
프로젝트/마일스톤 assignedContacts에는 멤버 Customer ID를 사용하고, 작업 assignedScoutelloUserIds 또는 영업 기회 ownerScoutelloUserId에는 User ID를 사용합니다. 작업/프로토콜 참조는 projectScoutelloId 또는 projectExternalId와 이에 대응하는 마일스톤/영업 기회 쌍을 허용합니다. 마일스톤만 지정된 링크에서는 프로젝트를 추론하며, 불일치하면 해당 배치 항목이 거부됩니다. 프로젝트 참여자는 추가 방식의 업서트로 처리되며 생략된 항목은 유지됩니다.
프로토콜은 연락처 없는 프로젝트/마일스톤 메모와 draft/final 상태를 지원합니다. 연결된 작업을 가져와도 알림이 발생하지 않으며 커뮤니케이션이 전송되지 않습니다. 목록 도구는 REST와 동일한 엔터티별 프로젝트, 상태, 할당 및 마감일 필터를 제공합니다. updatedSince를 포함한 정확한 필터를 각 커서 페이지에 전달합니다. 전체 계약과 null/생략 의미는 API 레퍼런스를 참조하세요.
종속된 각 배치를 검증하고 적용한 후 모든 결과를 확인하고 레코드를 다시 조회한 다음에야 데이터 입력이 완료된 것으로 처리합니다. 드라이 런만으로는 다른 드라이 런에서만 존재하는 상위 항목을 확인할 수 없습니다. scoutelloId를 사용하여 모호한 초기 링크를 다시 시도할 때는 먼저 외부 ID로 조회합니다. 링크가 생성된 후에는 부트스트랩 ID를 재생할 수 없습니다.
영업 프로젝트 에이전트 지침
영업 프로젝트에 생성되거나 재사용되는 모든 연락처는 contacts_batch_upsert에서 projectScoutelloId 또는 projectExternalId를 사용하여 해당 프로젝트를 명시적으로 참조해야 합니다. 메모나 외부 ID에서 프로젝트를 언급하는 것만으로는 멤버십이 생성되지 않습니다. 프로젝트 참조가 포함된 연락처 쓰기 작업에도 projects.write가 필요합니다. contacts.read 및 projects.read로 연락처를 다시 조회하고 projectParticipations를 확인합니다. 기존 멤버십과 그룹은 유지합니다. 프로젝트 외부의 일반 연락처에는 프로젝트 참조가 필요하지 않습니다.
회사와 검증된 개인은 별도의 연락처로 유지합니다. 개인을 회사에 연결할 때는 companyScoutelloId 또는 companyExternalId를 사용하며, companyName만 사용해서는 안 됩니다. 연락처, 회사 관계 및 멤버십 변경은 배치 항목별로 원자적으로 처리됩니다. 참조가 유효하지 않으면 연락처가 부분적으로 생성되지 않습니다. 개인을 추측하여 생성하거나 출처 태그를 적용하지 마세요.
발신 이메일은 프로토콜 본문이 아니라 mail_drafts_batch_upsert를 사용하여 준비합니다. 새로운 mail-drafts.read 및 mail-drafts.write 범위를 명시적으로 부여합니다. 준비 작업에는 contacts.read 및 projects.write도 필요합니다. 기존 인증 정보에는 새 권한이 자동으로 부여되지 않습니다. 안정적인 외부 ID, 생성 시 expectedVersion: 0, 명시적인 프로젝트/연락처 참조, 승인된 승인자의 User ID, 구성된 organization 또는 personal 발신자 범위를 사용합니다. 수신자 주소나 발신자 구성을 추측하지 마세요.
조사 내용은 content.notes에 유지하고, content.subject 및 content.body만 발신용 문구로 사용합니다. 초안 생성 시 해당 연락처가 프로젝트 참여자인지 확인합니다. 업데이트에는 최신 조회에서 반환된 버전을 사용해야 하며, 검토되었거나 발송된 초안은 수정할 수 없습니다. 동일한 요청을 다시 시도하면 새로운 검토를 생성하지 않고 원래 초안을 반환합니다. 해당 초안의 reviewUrl, draftVersion, contentHash, 승인/발송 상태 및 최종 mailScoutelloId를 다시 조회합니다.
지정된 담당자만 기존 검토 화면을 통해 승인하고 발송할 수 있습니다. 통합은 초안 작성 권한이 있어도 승인, 발송 또는 전송할 수 없습니다. 기존 초안을 변환할 때 원래 프로토콜을 유지하고 대체 항목을 상호 참조합니다. 대기 중이거나 모호한 전송 실패는 반드시 조사해야 하며, 맹목적으로 다시 보내서는 안 됩니다.
소셜 게시물 준비
필요에 따라 social-channels.read, social-posts.read, social-post-drafts.read 및
social-post-drafts.write를 부여합니다. members_list(members.read)는
검토자 사용자 ID를 검색할 수 있습니다. 소셜 도구는 해당 범위가 부여된 경우에만 표시됩니다:
| 범위 | 도구 |
|---|---|
social-channels.read | social_channels_list |
social-posts.read | social_posts_list, social_posts_get |
social-post-drafts.read | social_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id |
social-post-drafts.write | social_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload |
채널 기능과 Scoutello가 생성한 기록을 확인하고, 에셋을 업로드한 다음, 지정된 검토자와 함께 채널별 변형을 모두 제출합니다. 업로드 도구는 HTTP PUT 지침을 반환합니다. MCP 외부에서 원본 파일 바이트를 전송한 후 { "assetId": "..." }로 업로드를 완료합니다. 도구 인수에 base64 파일을 삽입하지 마세요.
새 초안에는 expectedVersion: 0를 사용하고, 대기 중인 수정에는 현재 버전을 사용합니다. mode: "validate"는 쓰기 작업을 수행하지 않습니다. 이 도구는 검토 URL을 반환하며, 대시보드를 사용하는 사람만 게시 또는 예약을 승인할 수 있습니다. 게시물을 승인, 게시, 취소 또는 삭제하는 MCP 도구는 없습니다. 초안 및 기록 도구를 폴링하여 승인 여부, 거부 사유 및 채널별 전송 결과를 확인합니다. 검토가 완료된 초안을 다시 제안하려면 새 외부 ID가 필요합니다.
입력 예시, 업로드 제한, 페이지 매김 및 지연된 검토 동작은 사람의 검토를 위한 소셜 게시물을 참조하세요.