페이싸인 MCP 연결 문서
AI 앱이나 자체 AI 에이전트에 페이싸인 MCP 연결을 붙이려는 개발자를 위한 문서입니다. 사용자의 말을 받아 전자문서를 만들고 서명 요청을 보낼 확인 화면까지 준비하는 기능을 연동합니다.
개요
MCP는 AI 앱이 외부 서비스의 도구를 쓸 수 있게 연결하는 표준 방식입니다.
페이싸인을 MCP로 연결하면 ChatGPT·Claude·Grok·Gemini 같은 AI 앱의 대화에서 보낼 문서를 말로 요청해 전자문서를 만들 수 있습니다. 이 연결은 사용자 확인 없이 문서를 보내지 않으며, 링크로 연 페이싸인 확인 화면에서 사람이 직접 [보내기]를 눌러야 합니다.
지원하는 MCP 프로토콜 버전은 2025-11-25와 2025-06-18입니다. MCP 접속 주소는 연동 상담에서 안내하며 이 문서에서는 <MCP 주소>로 적고, POST 요청만 받으며 POST가 아닌 요청에는 405가 옵니다.
API와 MCP의 차이
연동 개발자는 서버 간 연동이면 API를, AI 에이전트 연결이면 MCP를 고릅니다. MCP 키와 API 키는 다른 열쇠입니다.
| 구분 | 페이싸인 API | 페이싸인 MCP |
|---|---|---|
| 용도 | 서버 간 연동 | AI 에이전트 연결 |
| 요청 방식 | REST 방식 및 JSON 본문 | <MCP 주소>로 POST 요청(프로토콜 버전 2025-11-25, 2025-06-18) |
| 인증 및 열쇠 | Api-Id와 Authorization 헤더(API 사용 요청 뒤 관리자 승인) | OAuth 인가 후 Authorization: Bearer 헤더(요청 헤더용 MCP 키 발급은 준비 중) |
연결·등록
이용 환경에 따라 연결을 시작하거나 연동 상담으로 앱 등록을 문의합니다.
페이싸인 연결이 등록된 AI 앱에서 연결을 시작하면 페이싸인 로그인·동의 화면이 열리고 처음 한 번 로그인하고 동의하면 연결되며, 계정이 없으면 로그인 화면의 회원가입으로 먼저 가입합니다.
Claude 앱(웹·데스크톱)의 «커넥터 추가»로 바로 연결하는 방법은 준비 중입니다. Claude Code처럼 요청 헤더를 넣을 수 있는 도구용 연결 열쇠인 MCP 키 발급은 준비 중입니다.
개발자 앱 등록 안내
여러 회원이 쓰는 앱을 연결하려면 연동 상담으로 앱 등록을 문의하고, 앱 등록은 페이싸인 담당자가 합니다. 앱이 스스로 등록하는 동적 등록은 없으며, 연결 방법이 맞지 않거나 미리 연결을 상의하려면 연동 상담으로 문의할 수 있습니다.
앱 등록을 문의할 때는 콜백 주소 전체 목록, client 인증 방식, 담당자를 알려 줍니다. 콜백 주소는 등록한 값과 글자까지 정확히 같아야 하며 HTTPS 주소를 받고, http는 호스트가 localhost·127.0.0.1·[::1]일 때만 받습니다.
client 인증 방식은 client_secret_basic 또는 client_secret_post이고, 비밀값 없는 공개 client는 받지 않습니다. 등록이 끝나면 client_id를 알려 주고, client 비밀값은 문서와 다른 통로로 따로 전달합니다.
인증
인가 방식은 Authorization Code + PKCE이고, code_challenge_method는 S256만 받습니다.
토큰 없이 MCP 주소를 부르면 401과 함께 WWW-Authenticate 헤더에 resource_metadata와 scope가 옵니다.
보호 자원 메타데이터(/.well-known/oauth-protected-resource/mcp)에서 인가 서버 주소를 읽고, 인가 서버 메타데이터에서 authorization_endpoint·token_endpoint·revocation_endpoint를 읽습니다.
토큰 없이 부른 응답 헤더
WWW-Authenticate: Bearer resource_metadata="<보호 자원 메타데이터 주소>", scope="paysign.document"인가 요청과 토큰 요청의 resource 값에는 MCP 주소를 넣으며, 값이 다르면 invalid_target 오류가 옵니다. scope에는 paysign.document가 반드시 있어야 하고, refresh token을 받으려면 scope에 offline_access를 함께 넣어야 합니다.
인가 요청 값
response_type=code&code_challenge_method=S256&resource=<MCP 주소>&scope=paysign.document offline_access동의 화면에서는 페이싸인 계정 비밀번호를 다시 입력하고 [허용]을 누릅니다. 관리자 계정은 연결할 수 없으며, 계정이 잠긴 동안에는 연결이 잠시 거부되고 잠금이 풀리면 다시 쓸 수 있습니다.
호출할 때 access token은 Authorization: Bearer 헤더로만 보내며, 주소 쿼리로 보내면 거부합니다.
호출 헤더
Authorization: Bearer <access token>토큰 유효 기간과 갱신·폐기
인가 코드는 60초 안에 한 번만 쓸 수 있고, access token은 5분 동안 쓸 수 있습니다. refresh token은 쓸 때마다 새로 발급되며 30일 동안 쓰지 않으면 만료되고, 연결은 동의한 날부터 90일이 지나면 만료되며 refresh token도 그날을 넘지 않습니다.
갱신은 연결당 한 번에 하나만 보내고 응답을 받으면 새 refresh token을 먼저 저장하며, 이미 쓴 인가 코드나 refresh token이 다시 오면 그 연결 전체를 끊습니다. 앱에서 연결을 끊을 때는 revocation_endpoint로 client 인증과 token을 form으로 POST하며 응답은 200입니다.
할 수 있는 일
페이싸인 MCP 연결에서 쓰는 도구 이름은 paysign_document 하나입니다.
이 도구는 사용자의 말을 받아 전자문서를 만들고 서명 요청을 보낼 확인 화면까지 준비합니다. 예제 서식은 근로계약서 3개·내용증명 6개·동의서 10개이고, 마지막 번호 «그 밖»을 고르면 새로 만들 수 있습니다.
처음 문서를 만들 때 AI 문서 작성 동의가 아직 없으면 «양식을 만들려면 AI 문서 작성에 동의해 주세요.»와 함께 동의 링크가 먼저 옵니다.
입력 항목
입력은 모두 선택 항목이고, 정해진 항목 밖의 항목을 넣으면 입력 오류입니다. 지금은 next.ask를 보내지 않으므로 사용자의 답은 message로 보냅니다.
| 항목 | 형식 및 제한 | 설명 |
|---|---|---|
| message | 최대 4,000자 | 사용자의 말을 그대로 넣는 칸입니다. |
| job | — | 이어서 진행할 작업 번호(응답 next.job 값)를 넣습니다. |
| values | — | next.ask로 물은 항목의 답을 넣는 칸입니다(지금은 next.ask를 보내지 않아 message로 답함). |
| files | 최대 5개 | 첨부 파일이며 항목마다 name·mime·data(base64)를 넣습니다. |
| request_id | 영문·숫자·_·- 64자 이하 | 앱이 정하는 요청 식별값으로 호출마다 새 값을 쓰고, 응답을 못 받아 다시 보낼 때만 같은 값을 씁니다. |
응답 항목
응답 값은 결과의 structuredContent에 있고, content[0].text에 같은 JSON이 있습니다.
| 항목 | 형식 및 제한 | 설명 |
|---|---|---|
| say | 1~1,000자 | 사용자에게 전할 문장이며, 번호 목록처럼 줄바꿈이 있으면 줄바꿈 그대로 보여 줍니다. |
| next.type | — | ask_user·open_link·wait·done 중 하나입니다. |
| next.job | — | 이어서 부를 때 넣을 작업 번호이며 없을 수 있습니다. |
| next.seconds | 1~60 | wait일 때 다시 부를 때까지의 초입니다. |
| link | HTTPS·2,000자 이하 또는 null | 페이싸인 확인 화면 주소 또는 null입니다. |
next.type별 처리 방법
| 값 | 뜻 | 앱 처리 방법 |
|---|---|---|
| ask_user | 사용자의 답이 필요함 | say를 보여 주고 사용자의 말을 message로, next.job을 job으로 넣어 다시 부릅니다. |
| open_link | link를 사용자에게 보여 줌 | link를 보여 주며, 다른 type에서도 link가 있으면 함께 보여 줍니다. |
| wait | 한 호출 안에서 잠시 기다려도 작업이 끝나지 않음 | next.seconds 뒤에(없으면 3초 뒤에) 같은 job만 넣어 다시 부릅니다. |
| done | 이 작업의 진행이 끝남 | 성공만 뜻하지 않으므로 say를 그대로 전합니다. |
대화 예
문서 종류를 말하고 빈칸을 채워 확인 화면 링크를 받기까지의 호출과 응답 흐름입니다.
사용자가 «근로계약서 보내고 싶어»처럼 보낼 문서를 말합니다. 문서 종류를 알아보지 못하면 페이싸인은 «어떤 문서를 보낼까요? 근로계약서·내용증명·동의서 중에서 말씀해 주세요»라고 묻습니다.
첫 호출
{"name": "paysign_document", "arguments": {"message": "근로계약서 보내고 싶어", "request_id": "req_example_a"}}근로계약서로 정해지면 페이싸인은 «근로계약서 예제를 골라 주세요. 번호로 답해 주시면 바로 시작해요.»라고 하고 번호 목록을 보냅니다. 목록은 1. 정규직 근로계약서 / 2. 단기(기간제) 근로계약서 / 3. 아르바이트(단시간) 근로계약서 / 4. 그 밖 — 기본 조건(정규직·월급·주 5일)으로 새로 만들기입니다.
예제 목록 응답
{"say": "근로계약서 예제를 골라 주세요. 번호로 답해 주시면 바로 시작해요.\n1. 정규직 근로계약서\n2. 단기(기간제) 근로계약서\n3. 아르바이트(단시간) 근로계약서\n4. 그 밖 — 기본 조건(정규직·월급·주 5일)으로 새로 만들기", "next": {"type": "ask_user", "job": "j_example"}, "link": null}사용자는 번호(예: 1)나 제목으로 답합니다. 예제로 시작하면 첫 안내는 «조항을 더 넣거나 빼려면 ‘○○ 조항 추가해줘’, ‘○○ 빼줘’처럼 말씀해 주세요.»이고, 그다음 빈칸을 하나씩 «○○ 값을 알려 주세요.» 꼴로 묻습니다(○○ = 칸 이름).
번호로 답하기
{"name": "paysign_document", "arguments": {"message": "1", "job": "j_example", "request_id": "req_example_b"}}빈칸을 다 채우면 페이싸인은 «내용을 모두 채웠어요. 링크에서 받는 분 정보를 입력하고 확인 후 보내 주세요.»라고 하고 확인 화면 링크를 보냅니다. 대화 예의 문장은 페이싸인이 보내는 안내이며, 연결한 AI 앱이 값과 상태는 그대로 두고 자연스러운 말로 바꿔 전할 수 있습니다.
확인 화면 응답
{"say": "내용을 모두 채웠어요. 링크에서 받는 분 정보를 입력하고 확인 후 보내 주세요.", "next": {"type": "open_link"}, "link": "<확인 화면 주소>"}링크로 연 확인 화면(«문서 확인 및 받는 분 입력»)에서 «문서 미리보기»로 만든 문서를 보고, 받는 분 이름과 휴대폰 번호를 입력합니다. 확인 화면은 예상 차감 포인트를 보여 주며 «보내기 전에 문서에 틀린 내용이 없는지 꼭 확인해 주세요.»라고 안내하고, 사람이 직접 [보내기]를 눌러야 합니다.
오류·한도
호출 한도는 tools/call에만 걸리며, 오류 종류에 따라 HTTP 상태나 도구 결과로 안내가 옵니다.
사용자 한도는 분당 30회이며 앱이 달라도 같은 사용자면 함께 세고, 앱 한도는 분당 600회입니다. 한도는 첫 호출부터 60초 동안 세고 그 시간이 끝나면 다시 0부터 세며, 한도를 넘으면 HTTP 429와 Retry-After 헤더(남은 초)가 오므로 그 시간이 지난 뒤 다시 부릅니다.
오류 코드 및 처리
처리 실패(포인트 부족·권한·서버 문제 등)는 isError 없이 일반 결과로 오고 say에 안내가 있으며, 포인트가 부족하면 say는 «포인트가 부족해요. 포인트를 충전한 뒤 다시 말씀해 주세요.»입니다.
| 코드·구분 | 원인 | 대응 방법 |
|---|---|---|
| 입력 오류 (isError: true) | 입력 형식·개수·크기가 틀린 경우 | 도구 결과에 isError: true가 오고, say에 있는 사용자용 문장을 확인합니다. |
| JSON-RPC -32601 | 없는 메서드를 부른 경우 | 지원하지 않는 메서드 오류이므로 메서드 이름을 확인합니다. |
| JSON-RPC -32602 | 목록에 없는 도구 이름을 부른 경우 | 지원하지 않는 도구 오류이므로 도구 이름(paysign_document)을 확인합니다. |
| HTTP 400 | 요청 형식이 틀렸거나 MCP-Protocol-Version 값이 지원 버전이 아닌 경우 | 요청 형식과 프로토콜 버전(2025-11-25, 2025-06-18)을 확인합니다. |
| HTTP 401 | 토큰이 없거나 만료·폐기된 경우 | refresh 뒤 다시 부르고 실패하면 다시 인가합니다. |
| HTTP 403 (insufficient_scope) | paysign.document 권한이 없는 경우 | paysign.document scope로 다시 인가합니다. |
| HTTP 403 (Origin) | 허용되지 않은 Origin의 요청인 경우 | 브라우저에서 직접 호출할 수 없으므로 서버 쪽에서 호출합니다. |
| HTTP 405 | POST가 아닌 요청을 보낸 경우 | MCP 주소는 POST 요청만 받으므로 POST로 호출합니다. |
| HTTP 413 | 요청 본문이 1MB를 넘은 경우 | 요청 본문 크기를 1MB 이하로 줄여서 보냅니다. |
| HTTP 429 | 호출 한도를 넘은 경우 | Retry-After 헤더(남은 초)의 시간이 지난 뒤 다시 부릅니다. |
| HTTP 500 | 서버 처리 오류 | 잠시 뒤 다시 부릅니다. |
| HTTP 503 | 인가 서버를 쓸 수 없는 경우 | 잠시 뒤 다시 부릅니다. |
보안
문서 보내기는 확인 화면에서 사람이 직접 누르고, 받는 분 정보는 확인 화면에서 입력합니다.
이 연결은 사용자 확인 없이 문서를 보내지 않습니다. 문서 보내기는 링크로 연 페이싸인 확인 화면에서 사람이 직접 [보내기]를 눌러야 합니다.
페이싸인이 문서 작성에 AI를 쓸 때 전화번호·이메일·생년월일·금액·날짜는 가린 뒤 AI로 보냅니다. 다만 표기에 따라 가리지 못하고 그대로 갈 수 있으며, 받는 분 이름·연락처는 대화가 아니라 링크로 연 확인 화면에서 입력합니다.
페이싸인 비밀번호를 바꾸면 연결이 끊기고, 다시 쓰려면 새로 동의합니다. 문의할 때는 시각, 호출 단계, HTTP 상태, request_id, 재현 순서를 보내고, Authorization 값·토큰·인가 코드·요청과 응답 본문은 빼야 합니다.
자주 묻는 질문
페이싸인 MCP 연결과 이용에 대해 자주 묻는 내용입니다.
대화만 해도 포인트가 차감되나요?
대화와 조회는 포인트가 차감되지 않습니다. 문서를 보낼 때 문서당 포인트가 차감되며, 확인 화면에서 예상 차감 포인트를 보여 줍니다.
AI가 대화만으로 문서를 바로 발송하나요?
이 연결은 사용자 확인 없이 문서를 보내지 않습니다. 링크로 연 페이싸인 확인 화면에서 받는 분 이름과 휴대폰 번호를 입력하고 사람이 직접 [보내기]를 눌러야 합니다.
MCP 키와 API 키는 같은 것인가요?
MCP 키와 API 키는 다른 열쇠입니다. API 키는 서버 간 연동용이며 API 사용 요청 뒤 관리자 승인을 받아 쓰고, MCP 키는 Claude Code처럼 요청 헤더를 넣을 수 있는 도구용 연결 열쇠이며 발급은 준비 중입니다.
페이싸인 비밀번호를 바꾸면 연결은 어떻게 되나요?
페이싸인 비밀번호를 바꾸면 연결이 끊깁니다. 다시 쓰려면 새로 동의합니다.
직접 쓰는 AI 도구에 연결할 수 있나요?
Claude 앱(웹·데스크톱)의 «커넥터 추가»로 바로 연결하는 방법은 준비 중입니다. Claude Code처럼 요청 헤더를 넣을 수 있는 도구용 MCP 키 발급도 준비 중이며, 미리 연결을 상의하려면 연동 상담으로 문의할 수 있습니다.