MCP 가이드
Claude·ChatGPT·Codex 같은 AI에 싸인딜을 연결하면, 말로 양식을 고르고, 값을 채우고, 서명할 사람을 정하고, 보낼 수 있어요. 지금 열려 있는 도구는 12개예요. 도구마다 입력과 출력은 MCP 도구 참조에서 코드 그대로 볼 수 있어요.
1. 연결하기
| 쓰는 곳 | 어떻게 | 키가 필요해요? |
|---|---|---|
| claude.ai 확인 중 | 커넥터 추가 화면에 https://mcp.signdeal.kr/mcp를 넣고 싸인딜 로그인으로 허용해요. 화면 이름과 순서는 앱 쪽 사정으로 바뀔 수 있어서 아직 확인하는 중이에요. | 아니요(로그인으로 허용) |
| ChatGPT 확인 중 | 커넥터(개발자 모드)에 같은 주소를 넣어요. 확인하는 중이에요. | 아니요(로그인으로 허용) |
| Claude Code | claude 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.
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. 아직 준비 중인 것
아래는 코드가 아직 없어서 쓸 수 없어요. 열리면 이 문서와 도구 참조가 코드에서 자동으로 바뀌어요.
- 내 PDF를 AI에게 올리고 칸을 자동으로 찾기 준비 중
- MCP로 칸 놓기·옮기기·지우기(
place_field같은 도구) 준비 중 - MCP로 PDF 한 장 바로 서명 받기(
send_document도구) 준비 중 — REST에서는 이미 API 참조의/api/contracts:send_document로 쓸 수 있어요. 칸 좌표는 서명 위치·좌표를 보세요.
5. 오류가 나오면
401은 키나 로그인이 틀렸다는 뜻이에요. 키를 새로 만들거나 커넥터를 다시 연결해 보세요. insufficient_scope는 그 키에 권한이 없다는 뜻이에요. 그 밖의 코드는 오류 코드 페이지에서 찾아보세요.
- 키를 대화창에 붙여 넣지 마세요. 설정 파일에만 넣어요. 새 나갔다면 바로 지우고 새로 만들어요.
- 다른 사람 번호로 시험하지 마세요. 내 번호나 미리보기만 써요.