싸인딜 개발자

MCP 가이드

Claude·ChatGPT·Codex 같은 AI에 싸인딜을 연결하면, 말로 양식을 고르고, 값을 채우고, 서명할 사람을 정하고, 보낼 수 있어요. 지금 열려 있는 도구는 12개예요. 도구마다 입력과 출력은 MCP 도구 참조에서 코드 그대로 볼 수 있어요.

1. 연결하기

쓰는 곳어떻게키가 필요해요?
claude.ai 확인 중커넥터 추가 화면에 https://mcp.signdeal.kr/mcp를 넣고 싸인딜 로그인으로 허용해요. 화면 이름과 순서는 앱 쪽 사정으로 바뀔 수 있어서 아직 확인하는 중이에요.아니요(로그인으로 허용)
ChatGPT 확인 중커넥터(개발자 모드)에 같은 주소를 넣어요. 확인하는 중이에요.아니요(로그인으로 허용)
Claude Codeclaude mcp add --transport http signdeal https://mcp.signdeal.kr/mcp --header "Authorization: Bearer 내_키"예
Codex · Cursor · Claude 데스크톱설정 파일에 주소와 Authorization: Bearer 내_키 헤더를 넣어요.예

키 받기: https://app.signdeal.kr/app/mcp에서 새 키를 만들어요. 키는 한 번만 보여 줘요. 연결 확인은 AI에게 "싸인딜 사용량 알려 줘."라고 해 보세요.

키마다 쓸 수 있는 일(스코프)이 정해져 있어요: contract:read, contract:draft, contract:send, document:read.

Python으로 직접 부를 때, 기본 urllib은 보안 장치에 막힐 수 있어요(403). requests를 쓰거나 User-Agent 헤더를 넣어 보세요.

2. 한눈에 보는 순서

하고 싶은 것이렇게 말해요AI가 부르는 도구
표준 양식으로 보내기"업무 위임장 양식으로 김직원한테 보내 줘"list_templates → get_template → (모자란 값은 물어봐요) → create_draft → add_signer → send_for_signature(미리보기) → send_for_signature(보내기)
AI가 새로 쓴 계약서"500만원 차용증 써서 보내 줘"generate_contract_from_text → create_draft → add_signer → set_signature_fields_auto → send_for_signature×2
확인하기"서명했어?" · "완료본 줘" · "무료 몇 건 남았어?"check_status · get_signed_document · list_contracts · get_usage

무료는 가입할 때 10건이에요(1회성). 서명자는 계약 하나에 2명에서 10명까지예요.

3. 꼭 알아 둘 것

양식의 빈칸은 먼저 물어보세요

표준 양식은 get_template으로 채울 값을 먼저 봐요. 필수 값이 비었는데 create_draft를 부르면 missing_required가 나와요. 빠진 값의 이름도 같이 알려 줘요.

// get_template 에 보내는 값
{ "template_id": "tpl_양식ID" }

계약서 글을 AI가 쓸 때

contract_type은 이 중 하나여야 해요: loan_iou, lease_residential, lease_commercial, sale_real_estate, service, p2p_used_goods, p2p_general, employment.

보내기는 두 번이에요

처음엔 dry_run: true로 미리보기를 받아요. 사람이 "보내"라고 하면 그때 dry_run: false와 미리보기에서 받은 confirmation_token, 그리고 idempotency_key를 같이 보내요. 확인표(confirmation_token)는 5분 안에, 한 번만 쓸 수 있어요.

// 1) 미리보기
{ "contract_id": "ct_…", "dry_run": true }

// 2) 보내기 (사람이 "보내" 한 뒤)
{ "contract_id": "ct_…", "dry_run": false,
  "confirmation_token": "(1에서 받은 값)",
  "idempotency_key": "ct_…-send-1" }

보낸 뒤에는 고칠 수 없어요

이미 보낸 계약서는 못 고쳐요. 웹에서 취소하고 새로 만들어요.

4. 아직 준비 중인 것

아래는 코드가 아직 없어서 쓸 수 없어요. 열리면 이 문서와 도구 참조가 코드에서 자동으로 바뀌어요.

5. 오류가 나오면

401은 키나 로그인이 틀렸다는 뜻이에요. 키를 새로 만들거나 커넥터를 다시 연결해 보세요. insufficient_scope는 그 키에 권한이 없다는 뜻이에요. 그 밖의 코드는 오류 코드 페이지에서 찾아보세요.

  1. 키를 대화창에 붙여 넣지 마세요. 설정 파일에만 넣어요. 새 나갔다면 바로 지우고 새로 만들어요.
  2. 다른 사람 번호로 시험하지 마세요. 내 번호나 미리보기만 써요.