headless

문서

// mcp

어떤 도구에든 headless MCP 연동하기

headless MCP는 AI 에이전트용 한국 금융 데이터 API 실행 표면입니다. @h6s-ai/cli mcp 하나로 동작합니다. Claude Code · Cursor · Gemini · 자체 MCP 클라이언트가 은행 입출금내역, 홈택스 세금계산서, 현금영수증, 법인카드 승인내역을 같은 도구 목록으로 호출합니다.

Hosted endpoint

자체 에이전트나 MCP 클라이언트가 원격 HTTP 서버를 지원한다면 https://mcp.h6s.ai/mcp 를 등록해 주세요. 인증은 REST API와 같은 API Key를 Authorization: Bearer 헤더로 보냅니다. 비교 기준은 Codef MCP 대안에 정리했습니다.

remote mcp
{
  "mcpServers": {
    "h6s": {
      "url": "https://mcp.h6s.ai/mcp",
      "headers": {
        "Authorization": "Bearer h6s_live_..."
      }
    }
  }
}
curl
curl https://mcp.h6s.ai/mcp \
  -H 'Authorization: Bearer h6s_live_...' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example","version":"0.0.0"}}}'

표준 매니페스트

아래 JSON을 자기 도구의 mcpServers 설정에 추가해 주세요. 별도 서버 호스팅 없이 로컬에서 npx 로 실행됩니다.

mcp.json
{
  "mcpServers": {
    "h6s": {
      "command": "npx",
      "args": ["-y", "@h6s-ai/cli", "mcp"],
      "env": { "H6S_API_KEY": "h6s_live_..." }
    }
  }
}

도구별 설정 위치

많이 쓰는 세 도구는 전용 가이드가 있습니다. 그 외 MCP 호환 클라이언트는 위 매니페스트를 도구의 MCP 설정 파일에 추가해 주세요.

인증

서버는 환경변수 H6S_API_KEY 를 먼저 보고, 없으면 ~/.h6s/config.json 의 현재 프로필을 사용합니다. 둘 다 없으면 도구 호출 시점에 인증 오류를 돌려줍니다.

terminal
# 환경변수로 직접 주입
export H6S_API_KEY=h6s_live_...

# 또는 CLI로 로그인 (~/.h6s/config.json 에 저장)
npx @h6s-ai/cli login

노출 도구

MCP 서버가 클라이언트에 등록하는 주요 도구입니다. 대부분의 시나리오는 h6s_fetch_data 하나로 끝나고, 오래 걸리는 조회는 h6s_fetch_data_start, h6s_fetch_data_status, h6s_fetch_data_results 로 이어서 확인합니다.

h6s_catalog
워크스페이스 capability 통합 발견. provider + 인증 수단 + schema + 공동인증서 메타를 한 번에 반환합니다.
h6s_list_providers
가용 금융기관(provider) 목록.
h6s_list_schemas
가용 데이터 schema 목록 (은행·홈택스·법인카드 등 데이터 종류).
h6s_get_schema
schema 상세와 입력 항목 정의(필수/선택/타입), 응답 메타.
h6s_list_credentials
워크스페이스에 등록된 자격증명 목록.
h6s_fetch_data
schema + provider + 기간으로 수집 요청 생성 · 짧은 폴링 · 결과 반환까지 시도하는 매크로. 계속 진행 중이면 pending 과 jobId 를 반환합니다.
h6s_fetch_data_start
수집 요청을 시작하고 data-job id 를 즉시 반환합니다.
h6s_fetch_data_status
data-job 상태를 확인합니다.
h6s_fetch_data_results
완료된 data-job 결과를 조회합니다.
h6s_credentials_create
자격증명을 등록합니다. 민감 값 전달 전 사용자 확인이 필요합니다.
h6s_validate_brn
사업자등록번호 10자리 형식과 체크섬을 확인합니다.
h6s_report_bug
API 사용 중 발견한 이상 동작을 운영 채널로 제보합니다.

다음 단계