API와 MCP

인증서 진단과 만료 감시를 AI 에이전트, 스크립트, CI 안에서 바로 씁니다. 가입도 키도 필요 없습니다.

AI 에이전트에서 (MCP)

원격 MCP 서버입니다. Streamable HTTP로 붙고 인증은 없습니다. 연결하면 에이전트가 "example.com 인증서 언제 만료돼?" 같은 질문에 이 도구를 씁니다.

https://certdesk.dev/mcp

claude mcp add --transport http certdesk https://certdesk.dev/mcp

// .cursor/mcp.json
{
  "mcpServers": {
    "certdesk": { "url": "https://certdesk.dev/mcp" }
  }
}

// .vscode/mcp.json
{
  "servers": {
    "certdesk": { "type": "http", "url": "https://certdesk.dev/mcp" }
  }
}

도구 7개

check_certificate: 도메인 하나를 판정합니다. 서버가 실제로 보낸 체인으로 검증, 만료, 폐기, 미반영 새 인증서, CA 사고 이력을 봅니다.
check_expiry: 도메인 5개까지 인증서 만료와 도메인 등록 만료를 합쳐 판정합니다.
check_security: TLS 버전, 보안 헤더, 리다이렉트, 키 강도로 웹서버 보안 등급을 매깁니다.
check_dns: 네임서버와 운영사, IP 소유 기관, CAA, SPF·DMARC, DNSSEC, 등록기관을 봅니다.
check_dns_propagation: 권한 네임서버, 국내 통신 3사, 공용 DNS의 응답을 비교합니다. 도메인 검증용 TXT·CNAME 확인에 씁니다.
explain_tls_error: 브라우저, curl, Java, Python, Node, Go, .NET 오류 메시지의 원인과 조치를 알려 줍니다.
watch_expiry: 무료 만료 감시를 신청합니다. 확인 메일의 링크를 눌러야 시작됩니다.

스크립트와 CI에서 (REST API v1)

JSON으로 응답합니다. 전체 명세는 /openapi.json (OpenAPI 3.1)

GET/api/v1/certificate?domain=도메인 하나의 판정과 근거 (/check와 같은 결과)

curl "https://certdesk.dev/api/v1/certificate?domain=example.com"

GET/api/v1/expiry?domains=a,b도메인 5개까지 판정 요약. CI 게이트와 인벤토리 점검용

curl "https://certdesk.dev/api/v1/expiry?domains=example.com,example.org"

GET/api/v1/security?domain=보안 등급과 항목별 결과

curl "https://certdesk.dev/api/v1/security?domain=example.com"

GET/api/v1/dns-info?domain=DNS와 호스팅 정보

curl "https://certdesk.dev/api/v1/dns-info?domain=example.com"

GET/api/v1/dns?name=&type=DNS 전파 비교 (권한 NS, KT, SKB, LG U+, Cloudflare, Google, Quad9, OpenDNS)

curl "https://certdesk.dev/api/v1/dns?name=_acme-challenge.example.com&type=TXT"

GET/api/v1/explain?error=오류 메시지 해설

curl "https://certdesk.dev/api/v1/explain?error=PKIX%20path%20building%20failed"

POST/api/v1/watch만료 감시 구독 요청. 확인 메일을 보내고 202를 돌려줍니다

curl -X POST https://certdesk.dev/api/v1/watch \
  -H "content-type: application/json" \
  -d '{"email":"you@example.com","domains":["example.com","mail.example.com:587"],"webhook":"https://hooks.slack.com/services/…"}'

CI에서 막기

# GitHub Actions: 판정이 OK가 아니면(WARN, CRITICAL, UNKNOWN) 작업 실패
- name: Check certificate
  run: |
    res=$(curl -sS --fail-with-body --retry 3 --retry-all-errors \
      "https://certdesk.dev/api/v1/expiry?domains=example.com&warnDays=30&critDays=15&client=gha")
    echo "$res" | jq -r '.results[0] | "\(.status): \(.headline)"'
    test "$(echo "$res" | jq -r '.results[0].status')" = "OK"

판정 값

OK정상검증 통과, 만료까지 여유 있음
WARN주의만료 30일 이내, 측정 지점 간 불일치 등
CRITICAL위험만료, 검증 실패, 폐기, 15일 이내
UNKNOWN측정 불가서버를 측정하지 못함. 정상이 아닙니다

기준은 warnDays, critDays(1~365, 기본 30·15)로 바꿉니다. 실제 적용값은 응답의 thresholds에 있습니다.

수명이 짧은 인증서는 기본값을 줄여 적용합니다. UNKNOWN이면 daysLeft는 null이고, CT 로그 값은 estimate(추정)로만 줍니다.

한도와 조건

30회/분: 요청 한도 (IP당). RateLimit-Policy 헤더로 알려 줍니다
10회/분: 캐시에 없는 새 측정 (IP당)
10분: 같은 도메인 결과 캐시. 보안 등급은 30분
1회/분: ?fresh=1 다시 측정 (도메인당)
5개: expiry 한 번에 판정하는 도메인 수
0원: 가입, 키 없음. 결과는 보증하지 않습니다(best-effort)

포트: domain=host:port나 &port=로 지정합니다. 그 밖의 포트는 400을 돌려줍니다.
TLS 443, 8443, 4443, 9443, 6443, 636, 465, 993, 995, 853, 5061, 3269, 8883. STARTTLS는 SMTP 25·587, IMAP 143, POP3 110, LDAP 389. 공용 측정망 비교는 443에서만 합니다. 한글 도메인은 punycode로 바꿔 측정하고, IP 주소와 사설 이름은 거부합니다.
측정 지점: 한국 A(체인과 폐기까지)와 공용 측정망 Globalping의 한국 B(KT), 해외(도쿄)에서 잽니다. 지점별 결과는 measuredFrom에 있습니다.
A가 멈추면 공용 측정망으로 대신 판정합니다. 공용 측정망은 계정 한도에 걸리거나 장애가 나면 익명 한도로 자동 전환합니다. 상태는 /status/에서 봅니다.
저장: 조회한 도메인은 결과 캐시(최대 6시간)와 운영 로그(3일) 말고는 남기지 않습니다.
호출 통계는 경로, 엔드포인트, 클라이언트 이름, 국가 단위로만 집계합니다. ?client=앱이름을 붙이면 어떤 도구에서 쓰는지 집계에 반영합니다(선택).
구독: 어디서 요청하든 받는 사람이 확인 메일의 링크를 눌러야 시작됩니다. 본인 주소만 쓰세요.

배지, 캘린더, RSS

README 배지

판정을 색으로 보여 줍니다. 정상은 초록, 주의는 노랑(남은 일수), 위험은 빨강, 측정 불가는 회색입니다. 최대 6시간 캐시합니다. 아래는 certdesk.dev의 실제 배지입니다.

[![SSL](https://certdesk.dev/badge/example.com.svg)](https://certdesk.dev/check/?domain=example.com)

만료 캘린더

캘린더 앱에 구독 주소로 넣습니다. 주의(30일 전), 임박(15일 전), 7일·3일·1일 전, 만료일에 일정이 들어갑니다. 기준은 ?warnDays=, critDays=로 바꿉니다.

https://certdesk.dev/calendar/example.com.ics