headless

// industry

회계법인 · 세무사

클라이언트 12곳을 한 matrix workflow 로. 자연어 조회까지.

// schemas

사용 스키마

  • hometax.tax-invoices.sales.v1
  • hometax.tax-invoices.purchase.v1
  • bank.transactions.cb.v1

// scenario

회계법인 — 클라이언트 자연어 조회

Claude Desktop 에서 "○○클라이언트 이번주 거래 알려줘" 한 줄. workspace 별로 분리된 다중 클라이언트 자료를 자연어로 횡단.

주기
임의
대상
여러 클라이언트를 동시에 보는 세무사·회계사.
채널
MCP

01사전 점검

아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.

  • API Key 가 있다 (MCP 설정 env 에 넣을 값)

    echo $H6S_API_KEY

    h6s_live_... 로 시작하는 키가 출력된다

    아니면 — 콘솔(https://h6s.ai)에서 발급 후 export H6S_API_KEY=h6s_live_...

  • 클라이언트별 워크스페이스 자격증명이 등록돼 있다 (MCP 는 등록 안 함)

    h6s credentials list

    대상 기관에 매칭되는 자격증명이 1건 이상 보인다

    아니면 — h6s credentials create --interactive --cert

  • CLI 가 글로벌 설치돼 있다 (MCP cold-start 회피)

    h6s --version

    버전 문자열이 출력된다

    아니면 — npm i -g @h6s-ai/cli

02실행

클라이언트별 설정 파일을 toolkit 이 생성·병합한다. 한 번만.

terminal
npx @h6s-ai/toolkit install --target=cursor   # 또는 --target=mcp | gemini

Claude Desktop 은 --target=mcp 출력을 claude_desktop_config.json 의 mcpServers 에 병합하고 env 블록에 H6S_API_KEY 를 넣는다. 등록 후 클라이언트 재시작.

등록이 끝나면 채팅창에 자연어 한 줄.

프롬프트

에이클라이언트 워크스페이스에서 이번주 입출금 받아서 특이 거래 있으면 표시해줘.

이렇게 보이면 성공

workspace: client-a (자동 해석)
입금 3건 +6,840,000 / 출금 5건 -2,120,000
특이 거래 1건 — 2026-04-29 -1,500,000 적요 불명

03검증

  • 클라이언트명을 자연어로 부르면 해당 워크스페이스로 해석되어 자료를 횡단한다.
  • 이번주 입출금 요약과 특이 거래가 채팅창에 직접 온다.

04흔한 에러

MCP 서버가 연결 안 됨 / handshake timeout

npx cold-start (npm cache hydration) 가 handshake 보다 느리다.

해결 npm i -g @h6s-ai/cli 로 글로벌 설치 후 클라이언트 재시작.

도구 호출 시 NO_API_KEY 친절 에러

MCP 설정의 env 블록에 H6S_API_KEY 가 빠졌다.

해결 설정 파일 mcpServers.h6s.env 에 H6S_API_KEY 추가 후 재시작.

CERT_EXPIRED · CERT_WRONG_PASSWORD

등록된 공동인증서가 만료됐거나 비밀번호가 틀렸다.

해결 h6s credentials update 로 갱신 후 재실행.

자격증명을 찾을 수 없음

MCP 는 자격증명 등록을 다루지 않는다.

해결 CLI(h6s credentials create) 또는 콘솔에서 먼저 등록.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

다른 클라이언트·기간

terminal
비클라이언트 지난달 매출 세금계산서 합계 알려줘

// scenario

회계법인 — 다중 클라이언트 matrix 수집

매월 1일 N개 클라이언트 자료를 matrix 로 병렬 수집, 클라이언트별 디렉터리로 분리해 한 PR.

주기
매월 1일 06:00 KST
대상
월말 마감용 자료를 클라이언트별로 받아둬야 하는 세무사무소.
채널
GitHub Actions

01사전 점검

아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.

  • repo secret H6S_API_KEY 가 등록돼 있다

    gh secret list

    목록에 H6S_API_KEY 가 보인다

    아니면 — gh secret set H6S_API_KEY # 또는 repo Settings → Secrets

  • 워크스페이스에 대상 자격증명이 있다

    h6s credentials list

    그 기관에 매칭되는 자격증명이 1건 이상 보인다

    아니면 — h6s credentials create --interactive --cert

  • Actions 가 PR 을 만들 수 있다

    repo Settings → Actions → General → Workflow permissions

    "Read and write" + "Allow GitHub Actions to create pull requests" 체크

    아니면 — 두 옵션을 켠다 (yml 의 permissions 블록만으로도 동작하지만 repo 설정이 우선).

  • 클라이언트별 API Key secret 이 등록돼 있다

    gh secret list

    H6S_API_KEY_CLIENT_A · _B · _C … 가 보인다

    아니면 — 각 클라이언트 워크스페이스의 API Key 를 secret 으로 등록(워크스페이스=클라이언트).

02실행

아래 파일을 .github/workflows/ 에 저장하고 기본 브랜치에 commit. 첫 검증은 Actions 탭 → Run workflow 로 수동 트리거.

yaml
# 회계법인이 매월 1일에 N개 클라이언트 자료를 matrix 로 병렬 수집해
# 클라이언트별 디렉터리로 정리한 한 PR 을 만든다.
# 각 클라이언트는 별도 워크스페이스 = 별도 API Key. secrets 에 클라이언트별로 등록.
name: 회계법인 다중 클라이언트 월말 수집

on:
  schedule:
    - cron: '0 21 1 * *'   # 매월 1일 21:00 UTC = 다음날 KST 06:00
  workflow_dispatch: {}

jobs:
  fetch:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    strategy:
      fail-fast: false
      matrix:
        client:
          - { code: client-a, api_key_secret: H6S_API_KEY_CLIENT_A }
          - { code: client-b, api_key_secret: H6S_API_KEY_CLIENT_B }
          - { code: client-c, api_key_secret: H6S_API_KEY_CLIENT_C }
    steps:
      - uses: actions/checkout@v6

      - id: prev-month
        run: echo "value=$(date -u -d '1 month ago' +%Y-%m)" >> "$GITHUB_OUTPUT"

      - id: fetch-bank
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets[matrix.client.api_key_secret] }}
          schema: bank.transactions.cb.v1
          provider: CB_KB
          month: ${{ steps.prev-month.outputs.value }}
          output-path: ./clients/${{ matrix.client.code }}/${{ steps.prev-month.outputs.value }}/bank/

      - id: fetch-sales
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets[matrix.client.api_key_secret] }}
          schema: hometax.tax-invoices.sales.v1
          provider: HOMETAX
          month: ${{ steps.prev-month.outputs.value }}
          output-path: ./clients/${{ matrix.client.code }}/${{ steps.prev-month.outputs.value }}/tax/

      - id: fetch-purchase
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets[matrix.client.api_key_secret] }}
          schema: hometax.tax-invoices.purchase.v1
          provider: HOMETAX
          month: ${{ steps.prev-month.outputs.value }}
          output-path: ./clients/${{ matrix.client.code }}/${{ steps.prev-month.outputs.value }}/tax/

      - uses: actions/upload-artifact@v4
        with:
          name: clients-${{ matrix.client.code }}-${{ steps.prev-month.outputs.value }}
          path: ./clients/${{ matrix.client.code }}/${{ steps.prev-month.outputs.value }}/
          retention-days: 30

  merge-pr:
    needs: fetch
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6

      - id: prev-month
        run: echo "value=$(date -u -d '1 month ago' +%Y-%m)" >> "$GITHUB_OUTPUT"

      - uses: actions/download-artifact@v4
        with:
          path: ./clients/

      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'clients-monthly · ${{ steps.prev-month.outputs.value }}'
          body: |
            자동 생성. 클라이언트별 디렉터리에 월별 자료 (입출금 + 매출/매입 세금계산서).

            기간: ${{ steps.prev-month.outputs.value }}
          branch: clients/${{ steps.prev-month.outputs.value }}
          commit-message: 'chore(clients): ${{ steps.prev-month.outputs.value }} 일괄 수집'
          add-paths: clients/

matrix.client 에 {code, api_key_secret} 한 줄만 추가하면 클라이언트 N배 확장.

03검증

  • Actions 에서 클라이언트 수만큼 fetch job 이 (일부 실패해도) 끝나고 merge-pr 초록.
  • clients/<월> 브랜치 PR 에 client-a/ client-b/ … 디렉터리별 자료가 모인다.
  • 한 클라이언트 자격증명 누락 시 그 job 만 실패.

04흔한 에러

워크플로우는 초록인데 PR 이 안 생긴다

Actions 의 PR 생성 권한이 막혀 있거나 변경 파일이 없다(중복 실행).

해결 repo Settings → Actions 에서 PR 생성 허용. 같은 기간 재실행이면 정상.

fetch step 에서 NO_API_KEY 로 실패

secret 이름이 yml 의 secrets.H6S_API_KEY 와 다르다.

해결 secret 을 정확히 H6S_API_KEY 로 등록.

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.

해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).

cron 시간이 지나도 안 돈다

yml 이 기본 브랜치에 없거나, repo 가 60일 비활성이라 scheduled workflow 가 멈췄다.

해결 기본 브랜치에 머지하고, 가끔 수동 트리거해 활성 유지.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

클라이언트 추가

yaml
- { code: client-d, api_key_secret: H6S_API_KEY_CLIENT_D }

현금영수증까지

yaml
- id: fetch-cash
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets[matrix.client.api_key_secret] }}
          schema: hometax.cash-receipts.sales.v1
          provider: HOMETAX
          month: ${{ steps.prev-month.outputs.value }}

// related

다른 각도에서 보기

headless

Get started

지금 가입하고 API 키를 발급받으세요.

회원가입