TL;DR

• AI 에이전트(Claude 등)로부터 호출할 수 있는
  MCP 서버를 공개했습니다. jp-pint-mcp

• 할 수 있는 일:
  적격 청구서의 등록 번호(T+13자리)를 국세청 공표 API에 라이브로 대조하여 「실재하는지·유효한지·사업자명」을 반환합니다. - 형식 체크(체크 디지트) 정도라면 누구나 작성할 수 있지만,
  「그 번호가 지금 이 순간 실재하고 유효한가」는 AI가 스스로 생성할 수 없는 1차 정보입니다. 그 부분을 MCP로 채웠습니다. - 의존성 제로,
  npx 한 번으로 실행.

npx github:junju523/jp-pint-mcp

왜 만들었는가

청구서 처리를 자동화할 때, 등록 번호 검증이 은근히 까다롭습니다.

• 형식이 올바른가 (T+숫자 13자리, 체크 디지트)
• 그 번호가 실재하며, 지금도 유효한가 (실효·취소되지 않았는가)
• 등록된 사업자명은 무엇인가

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를 호출해보고 나서야 알게 된 사양들이 몇 가지 있었습니다.

• number는 「T+13자리」. 숫자만 13자리를 보내면 HTTP 400 에러가 발생합니다. - 응답 announcement[]에 registratedNumber (철자는 공식 명칭 그대로) / registrationDate / expireDate (실효) / disposalDate (취소) / name / process / latest가 들어갑니다. - 당초 「숫자만 송신·실효 여부만 판정」하도록 작성했던 것은 실제 사양과 차이가 있어, 실제 HTTP 검증을 통해 수정했습니다.

사양의 세부 사항은 「개요 페이지」가 아니라, 별책인 「리퀘스트 설정 방법 및 제공 데이터 내용에 대하여」(Web-API 사양서)에 적혀 있습니다.

또한, 국세청 Web-API는 앱 ID (이용 신청 → 승인)가 필요하며, 즉시 승인되는 것이 아니라 심사가 있습니다 (출처 표시도 의무). 즉, 「로직은 스스로 작성할 수 있어도, 실재 확인 부분만큼은 신청하여 승인을 기다리지 않으면 작동할 수 없다」는 것입니다. 그 과정을 마친 뒤 MCP/API로서 공개해 두었으므로, 신청 없이 그대로 실재 확인 기능만 사용할 수 있습니다.

MCP 서버 구현 팁

• 의존성 제로: stdio의 JSON-RPC를 직접 구현했습니다. initialize / tools/list / tools/call만 필요하므로, 프레임워크 없이 충분히 가볍게 작성할 수 있습니다. - stdin close 시의 race condition: 실행 중인(in-flight) 비동기 fetch를 기다리지 않고 process.exit(0)을 호출하면 응답이 유실됩니다. CI/배치 프로브에서 무응답이 되므로, 종료 처리는 기다린 후에 해야 합니다.

브라우저/HTTP로도 테스트 가능 (호스트 버전 API)

MCP를 설정하지 않아도, 호스트 버전 API로 동일한 조회를 테스트할 수 있습니다.

• 등록 번호 체크 (실재 확인)는 키(Key) 없이도 호출할 수 있습니다. 우선 여기서부터 확인해 보세요: -
  https://jp-pint-rryxbfcsxq-an.a.run.app
  (번호를 입력하기만 하면 출처와 함께 실재/유효/사업자명을 반환합니다)

• 송장 전체 검증 (기재 6개 항목 · 세금 구분)은 **무료 키 (월 200회)**로 이용 가능합니다. LP에서 발행할 수 있습니다.

"자신의 에이전트/SaaS에 통합하고 싶다", "이런 종류의 대조 기능도 필요하다" 등의 의견이 있다면 리포지토리(Repository)의 Issue나 기사 댓글로 남겨주세요.

마치며

"로직은 에이전트가 작성할 수 있다. 작성할 수 없는 것은 '유지되는 1차 정보'이다"라는 구분점을 바탕으로, MCP의 가치가 발휘될 수 있는 곳을 선택했습니다. 같은 발상으로 관보·고시 기반의 다른 공공 데이터도 MCP화할 여지가 충분할 것이라고 생각합니다.

• 리포지토리 (Repository): https://github.com/junju523/jp-pint-mcp
• 피드백을 환영합니다.

이 서비스는 국세청 적격 청구서 발행 사업자 공표 시스템의 Web-API 기능을 이용하여 취득한 정보를 바탕으로 작성되었습니다.

Discussion