Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
국세청 API를 활용하여 인보이스 등록 번호의 실재 여부와 사업자 정보를 검증하는 MCP 서버를 공개했습니다. LLM의 할루시네이션을 방지하고 외부의 실시간 데이터를 에이전트에 연결하는 MCP의 유스케이스를 제시합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기AI 에이전트(Claude 등)로부터 호출할 수 있는
MCP 서버를 공개했습니다. jp-pint-mcp
할 수 있는 일:
적격 청구서의 등록 번호(T+13자리)를 국세청 공표 API에 라이브로 대조하여 「실재하는지·유효한지·사업자명」을 반환합니다. - 형식 체크(체크 디지트) 정도라면 누구나 작성할 수 있지만,
「그 번호가 지금 이 순간 실재하고 유효한가」는 AI가 스스로 생성할 수 없는 1차 정보입니다. 그 부분을 MCP로 채웠습니다. - 의존성 제로,
npx 한 번으로 실행.
npx github:junju523/jp-pint-mcp
청구서 처리를 자동화할 때, 등록 번호 검증이 은근히 까다롭습니다.
1번은 로직이므로 AI 에이전트도 그 자리에서 구현할 수 있습니다. 하지만, 2번과 3번은 국세청의 공표 데이터를 조회하지 않으면 알 수 없습니다. LLM은 「그럴듯한 사업자명」을 아무렇지 않게 날조하기 때문에, 이 부분을 외부의 진실(External Truth)에 연결할 필요가 있습니다.
이는 MCP (Model Context Protocol)의 좋은 유스케이스입니다. 에이전트에게 「등록 번호를 실재 확인하는 도구」를 쥐여주면, 할루시네이션 (Hallucination) 없이 사실을 반환할 수 있습니다.
MCP 클라이언트 (Claude Desktop 등) 설정에 추가합니다.
{
"mcpServers": {
"jp-pint": {
...
}
}
}
공개 도구:
| tool | 설명 |
|---|---|
check_registration_number | 등록 번호를 형식 + 실재 확인 (실재/유효/사업자명/등록일/실효일을 반환) |
validate_invoice | 적격 청구서의 기재 6항목·세율 구분 (8/10%)을 검증 |
실행 예시 (도요타 자동차 T1180301018771):
{
"registratedNumber": "T1180301018771",
"exists": true,
...
}
미등록 번호는 exists: false, 형식 부적합은 valid: false를 반환합니다.
실제 API를 호출해보고 나서야 알게 된 사양들이 몇 가지 있었습니다.
announcement[]에 registratedNumber (철자는 공식 명칭 그대로) / registrationDate / expireDate (실효) / disposalDate (취소) / name / process / latest가 들어갑니다. - 당초 「숫자만 송신·실효 여부만 판정」하도록 작성했던 것은 실제 사양과 차이가 있어, 실제 HTTP 검증을 통해 수정했습니다.사양의 세부 사항은 「개요 페이지」가 아니라, 별책인 「리퀘스트 설정 방법 및 제공 데이터 내용에 대하여」(Web-API 사양서)에 적혀 있습니다.
또한, 국세청 Web-API는 앱 ID (이용 신청 → 승인)가 필요하며, 즉시 승인되는 것이 아니라 심사가 있습니다 (출처 표시도 의무). 즉, 「로직은 스스로 작성할 수 있어도, 실재 확인 부분만큼은 신청하여 승인을 기다리지 않으면 작동할 수 없다」는 것입니다. 그 과정을 마친 뒤 MCP/API로서 공개해 두었으므로, 신청 없이 그대로 실재 확인 기능만 사용할 수 있습니다.
initialize / tools/list / tools/call만 필요하므로, 프레임워크 없이 충분히 가볍게 작성할 수 있습니다. - stdin close 시의 race condition: 실행 중인(in-flight) 비동기 fetch를 기다리지 않고 process.exit(0)을 호출하면 응답이 유실됩니다. CI/배치 프로브에서 무응답이 되므로, 종료 처리는 기다린 후에 해야 합니다.MCP를 설정하지 않아도, 호스트 버전 API로 동일한 조회를 테스트할 수 있습니다.
등록 번호 체크 (실재 확인)는 키(Key) 없이도 호출할 수 있습니다. 우선 여기서부터 확인해 보세요: -
https://jp-pint-rryxbfcsxq-an.a.run.app
(번호를 입력하기만 하면 출처와 함께 실재/유효/사업자명을 반환합니다)
송장 전체 검증 (기재 6개 항목 · 세금 구분)은 **무료 키 (월 200회)**로 이용 가능합니다. LP에서 발행할 수 있습니다.
"자신의 에이전트/SaaS에 통합하고 싶다", "이런 종류의 대조 기능도 필요하다" 등의 의견이 있다면 리포지토리(Repository)의 Issue나 기사 댓글로 남겨주세요.
"로직은 에이전트가 작성할 수 있다. 작성할 수 없는 것은 '유지되는 1차 정보'이다"라는 구분점을 바탕으로, MCP의 가치가 발휘될 수 있는 곳을 선택했습니다. 같은 발상으로 관보·고시 기반의 다른 공공 데이터도 MCP화할 여지가 충분할 것이라고 생각합니다.
이 서비스는 국세청 적격 청구서 발행 사업자 공표 시스템의 Web-API 기능을 이용하여 취득한 정보를 바탕으로 작성되었습니다.
