SW CPAs API·MCP 개발자 문서 | 에스더블유 공인회계사 사무소

결론부터: SW CPAs API와 MCP 서버는 가입이나 API 키 없이 바로 씁니다. 사무소 정보·서비스·글 검색·미국 진출 진단은 읽기 전용이고, 쓰기 작업은 사용자를 대신한 상담 신청 하나뿐입니다. 모든 기능은 무료입니다.

한눈에 보기

OpenAPI 3.1 계약: /openapi.json
MCP 서버(제품): https://sw-cpas.co.kr/mcp (Streamable HTTP) · 서버 카드 /.well-known/mcp/server-card.json
MCP 서버(문서): https://sw-cpas.co.kr/mcp/docs · 서버 카드 /.well-known/mcp/docs-server-card.json
NLWeb 질의: GET /ask?q=… 또는 POST /ask
WebMCP: 홈 화면이 브라우저 에이전트용 도구를 등록합니다.
에이전트 자원 목록: /.well-known/ard.json · API 목록 /.well-known/api-catalog · 에이전트 스킬 /.well-known/agent-skills/index.json
사이트 안내: /llms.txt · 이 섹션 안내 /developers/llms.txt · 인증 안내 /auth.md
공식 에이전트 키트(GitHub): samorj16-bot/sw-cpas-agent (새 창에서 열림). 에이전트 플러그인, 스킬, AGENTS.md, 명령줄 도구가 있습니다. 명령줄 도구는 npm 패키지 sw-cpas-mcp (새 창에서 열림)로도 설치할 수 있습니다(npx sw-cpas-mcp firm, 인자 없이 실행하면 표준입출력 MCP 서버). MCP 공식 레지스트리 이름은 kr.co.sw-cpas/mcp 입니다.

빠른 시작

가입 단계가 없으므로 첫 호출이 곧 시작입니다.

curl https://sw-cpas.co.kr/api/v1/firm
curl "https://sw-cpas.co.kr/api/v1/insights?q=LLC&limit=5"
curl -X POST https://sw-cpas.co.kr/api/v1/us-incorporation/evaluate \
  -H "Content-Type: application/json" \
  -d '{"answers":{"business_type":"saas","presence":"none","owner":"korean_corp","funding":"yes_12mo","visa":"stay_korea","profit":"reinvest","privacy":"none","revenue":"lt_100k"}}'

엔드포인트

메서드	경로	내용
`GET`	`/api/v1/firm`	사무소 정보(대표 자격·사무소·연락처·견적 방식)
`GET`	`/api/v1/services`	서비스 목록과 각 페이지 주소, 무료 도구
`GET`	`/api/v1/insights`	글 목록·검색(q, category, limit 1~50, cursor)
`GET`	`/api/v1/us-incorporation/questions`	미국 진출 진단 질문과 허용 값
`POST`	`/api/v1/us-incorporation/evaluate`	추천 설립 주·법인 형태·1년차 비용 계산(저장하지 않음)
`POST`	`/api/v1/consultation-requests`	사용자를 대신한 상담 신청. 202 와 상태 주소(Location)를 돌려줌(dry_run 시험 모드, Idempotency-Key)
`GET`	`/api/v1/consultation-requests/{request_id}`	상담 신청 접수 상태(개인정보 없음)

목록 응답은 next_cursor 로 다음 페이지를 이어 받습니다. 요청·응답 형식은 모두 OpenAPI 계약에 있습니다.

MCP 서버 연결

제품 서버 도구: get_firm_profile, list_services, search_insights, get_us_incorporation_questions, evaluate_us_incorporation, request_consultation. 문서 서버 도구: search_docs, get_document, ask_site. 모든 도구는 입력·출력 스키마와 읽기 전용 여부 표시를 갖습니다.

{
  "mcpServers": {
    "sw-cpas": { "type": "http", "url": "https://sw-cpas.co.kr/mcp" },
    "sw-cpas-docs": { "type": "http", "url": "https://sw-cpas.co.kr/mcp/docs" }
  }
}

상담 신청

에이전트는 사용자를 대신해 상담을 신청할 수 있습니다. 실제 이메일이 사무소에 전달되므로 다음을 지켜 주세요.

이름·이메일·상담 내용을 사용자에게 확인합니다. 모르는 값을 지어내지 않습니다.
사용자가 개인정보 처리방침에 동의한 경우에만 consent_privacy: true 를 보냅니다.
먼저 dry_run: true 로 검증한 뒤 한 번만 보냅니다. 재시도에는 같은 Idempotency-Key 를 씁니다.

접수되면 202 Accepted 와 함께 request_id·Location 헤더를 돌려줍니다. 그 주소(GET /api/v1/consultation-requests/{request_id})로 접수 상태를 다시 확인할 수 있습니다. 접수 후 1영업일 이내 담당 CPA가 이메일 또는 전화로 연락드립니다.

curl -X POST https://sw-cpas.co.kr/api/v1/consultation-requests \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9a7e-0b2d-4c55-9a51-2f8e6d1b7c40" \
  -d '{"name":"홍길동","email":"[email protected]","message":"미국 델라웨어 C-Corp 설립과 한국 해외직접투자 신고 상담을 원합니다.","consent_privacy":true,"dry_run":true}'

오류 형식

모든 오류는 같은 JSON 모양으로 돌아옵니다. code 로 분기하고 hint 를 따라 고칩니다.

{
  "type": "https://sw-cpas.co.kr/developers/#error-invalid_answers",
  "title": "Some answers are missing or not allowed.",
  "status": 422,
  "detail": "GET /api/v1/us-incorporation/questions lists every question id and allowed value.",
  "error": {
    "code": "invalid_answers",
    "message": "Some answers are missing or not allowed.",
    "hint": "GET /api/v1/us-incorporation/questions lists every question id and allowed value.",
    "status": 422,
    "docs": "https://sw-cpas.co.kr/developers/",
    "details": [{ "field": "presence", "message": "미응답: presence" }]
  }
}

오류 코드(error.code)는 다음과 같습니다. type 은 이 목록의 해당 항목을 가리킵니다.

not_found: 없는 경로나 요청 ID
method_not_allowed: 허용되지 않는 HTTP 메서드(Allow 헤더 참고)
invalid_json: 본문이 JSON 객체가 아님
invalid_parameter: 질의 매개변수 값이 범위를 벗어남
invalid_answers: 진단 답변 누락·허용되지 않는 값
invalid_request: 상담 신청 필드 누락·형식 오류·동의 없음
missing_query: /ask 에 질문이 없음
rate_limited: 요청 한도 초과(Retry-After 만큼 기다린 뒤 재시도)
service_unavailable: 상담 신청을 잠시 받을 수 없음
delivery_failed: 저장·전달 실패(같은 Idempotency-Key 로 재시도)
internal_error: 서버 오류(한 번 재시도)
request_failed: 그 밖의 요청 실패
idempotency_key_reused: 같은 Idempotency-Key 를 다른 신청 내용에 다시 씀(새 신청에는 새 키를 쓴다)
request_in_progress: 같은 키의 신청이 아직 처리 중(잠시 뒤 같은 키로 재시도)

요청 한도

읽기: 클라이언트당 분당 60회, 쓰기: 분당 10회. 응답의 RateLimit-Limit·RateLimit-Remaining·RateLimit-Reset 헤더로 남은 횟수를 알 수 있습니다.
상담 신청: 클라이언트당 시간당 3건, 사이트 전체 하루 20건.
한도를 넘으면 429 와 Retry-After 헤더를 돌려줍니다.

인증과 시험 모드

인증이 필요 없습니다. 개발자 포털이나 키 발급 절차도 없습니다. 보호 자원 메타데이터(/.well-known/oauth-protected-resource, RFC 9728)도 토큰을 쓰지 않는다고 밝힙니다. 상담 신청은 dry_run: true 가 시험 모드이며, 저장·발송 없이 검증 결과만 돌려줍니다. 연동을 시험할 때는 시험 환경 https://sw-cpas.co.kr/sandbox/api/v1/… 을 쓰세요. 응답에 X-Environment: sandbox 가 붙고, 이곳으로 보낸 상담 신청은 검증만 하고 저장·발송하지 않습니다. 자세한 내용은 /auth.md에 있습니다.

버전과 변경 정책

경로에 버전(/api/v1)을 붙이고, 모든 응답에 API-Version 헤더를 답니다. 필드를 추가하는 변경은 버전을 바꾸지 않습니다. 기존 동작을 깨는 변경은 새 버전 경로로 내고, 옛 버전에는 최소 90일 동안 Deprecation·Sunset 헤더로 예고합니다.

문의

연동 중 문제가 있으면 [email protected] 으로 알려 주세요.

SW CPAs API · MCP 개발자 문서