API가 뭔지, API Key가 뭔지, Claude API는 어떻게 작동하는지, MCP와 어떻게 연결되는지.
비개발자도 이해할 수 있는 눈높이에서 API의 모든 것을 배웁니다.
✅ API 개념 — 비유와 예시로 API가 뭔지 명확히 이해
✅ 요청 구조 — 엔드포인트, API Key, JSON 요청/응답을 흐름도로 파악
✅ Claude API — Messages API, 모델 선택, 토큰, 도구 사용까지
✅ MCP 연결 — API 위에 MCP가 어떻게 얹히는지 완전 이해
✅ 활용 사례 — API로 무엇을 만들 수 있는지 7가지 실전 안내
API를 한 번도 안 써본 사람도 이해할 수 있도록, 비유부터 시작합니다.
레스토랑에 가면: ① 메뉴판을 봅니다 (어떤 것을 주문할 수 있는지) → ② 웨이터에게 주문합니다 (정해진 형식으로 요청) → ③ 주방에서 요리가 나옵니다 (결과를 받음). API도 정확히 이렇게 작동합니다.
| 상황 | 내부적으로 일어나는 일 | 사용되는 API |
|---|---|---|
| 카카오맵 길찾기 | 출발지·도착지를 보내면 최적 경로를 받음 | 카카오 경로 API |
| "카카오로 로그인" | 카카오가 신원을 확인하고 토큰을 발급 | 카카오 OAuth API |
| Claude에게 질문 | 메시지를 보내면 AI 응답을 받음 | Claude Messages API |
| 날씨 앱이 날씨 표시 | 위치 좌표를 보내면 날씨 데이터를 받음 | 기상 데이터 API |
| 결제창에서 카드 결제 | 카드 정보를 보내면 승인/거절을 받음 | PG사 결제 API |
API 요청이 어떤 부품들로 이루어져 있는지, 하나씩 뜯어봅니다.
API 서버의 특정 기능에 접근하는 URL입니다. 레스토랑의 "주소"와 같습니다.
API를 사용할 권한이 있음을 증명하는 비밀 키입니다. 콘서트 입장권처럼, 이게 없으면 서버가 요청을 거부합니다.
API에게 "무엇을 해달라"는 구체적인 내용입니다. JSON 형식으로 작성합니다.
서버가 처리한 결과를 JSON으로 돌려줍니다.
| 메서드 | 의미 | 비유 | Claude API? |
|---|---|---|---|
| GET | 데이터 가져오기 | 메뉴판 보기 | — |
| POST | 데이터 보내고 처리 | 주문하기 | ✅ 사용 |
| PUT | 데이터 수정 | 주문 변경 | — |
| DELETE | 데이터 삭제 | 주문 취소 | — |
| 코드 | 의미 | 대처법 |
|---|---|---|
| 200 OK | 성공! 정상 응답 | 응답 데이터를 사용하면 됨 |
| 400 Bad Request | 요청 형식이 잘못됨 | JSON 구조와 파라미터 확인 |
| 401 Unauthorized | API Key 없거나 잘못됨 | API Key 확인 |
| 429 Too Many Requests | 요청 너무 많음 (Rate Limit) | 잠시 기다렸다가 재시도 |
| 500 Server Error | 서버 측 문제 | 잠시 후 재시도, 상태 페이지 확인 |
Claude API를 사용하기 위해 알아야 할 핵심 사항을 단계별로 배웁니다.
API를 제대로 이해하기 위해 반드시 알아야 할 개념들입니다.
MCP(Model Context Protocol)가 API와 어떻게 다른지, 그리고 왜 강력한지 이해합니다.
예시: "내 Gmail에서 오늘 받은 미팅 초대를 찾아서 구글 캘린더에 추가해줘"
각 서비스는 자체 API를 가지고 있고, MCP 서버가 그 API를 Claude와 연결해 줍니다.
Claude API를 활용한 실전 활용 사례 7가지입니다.
각 박사를 클릭하면 그 박사의 관점에서 API를 설명해 줍니다.
단계별로 체크하면서 API 이해도를 높여가세요.
12문항으로 API 기초 이해도를 확인합니다.
모르는 용어가 나왔을 때 바로 찾아보세요.
자주 참고할 내용을 클립보드에 복사해 두세요.
API = 프로그램끼리 대화하는 규칙과 형식 (메뉴판+웨이터)
엔드포인트 = API 기능에 접근하는 URL 주소
API Key = API 사용 권한을 증명하는 비밀 키 (절대 공개 금지)
JSON = API 요청/응답에 쓰는 데이터 형식 {키: 값}
토큰 = AI가 텍스트를 처리하는 단위 (한국어 1글자 ≈ 1-2토큰)
MCP = AI가 API를 자동으로 호출하게 해주는 연결 레이어
HTTP = 웹에서 데이터를 주고받는 프로토콜
REST API = URL로 자원을 나타내고 HTTP 메서드로 행동을 표현하는 방식엔드포인트: POST https://api.anthropic.com/v1/messages
헤더:
x-api-key: {API_KEY}
anthropic-version: 2023-06-01
content-type: application/json
본문 (JSON):
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": "역할/지시 프롬프트",
"messages": [
{"role": "user", "content": "사용자 메시지"}
]
}
응답에서 꺼낼 것:
data.content[0].text → AI 답변 텍스트
data.usage.input_tokens → 입력 토큰 수
data.usage.output_tokens → 출력 토큰 수claude-opus-4-6 → 최고 품질, 복잡한 추론·분석 ($15/$75 per 1M) claude-sonnet-4-6 → 품질+속도 균형, 대부분의 작업 ($3/$15 per 1M) claude-haiku-4-5 → 빠르고 저렴, 단순 분류·요약 ($0.80/$4 per 1M) 선택 기준: - 복잡한 분석/코딩 → Opus - 일반 대화/글쓰기 → Sonnet - 빠른 분류/태깅 → Haiku - 비용 절약 필요 → Haiku 먼저 시도
❌ 절대 하지 말 것: - 코드에 직접 API Key 입력 (const apiKey = "sk-ant-...") - GitHub에 API Key 포함된 파일 올리기 - 채팅이나 이메일로 API Key 공유 - 프론트엔드 JavaScript에 API Key 노출 ✅ 올바른 방법: - .env 파일에 저장: ANTHROPIC_API_KEY=sk-ant-... - .gitignore에 .env 추가 - 서버 사이드에서만 API 호출 - 정기적으로 Key 교체 (분기 1회) - 용도별로 다른 Key 발급
토큰 기준 (대략): - 영어 1단어 ≈ 1.3 토큰 - 한국어 1글자 ≈ 1~2 토큰 - 1페이지 문서 ≈ 500~700 토큰 비용 예시 (Sonnet 4.6 기준 $3/$15 per 1M): - 짧은 Q&A (100/200 토큰) ≈ $0.000030/건 - 문서 요약 (2000/500 토큰) ≈ $0.000135/건 - 하루 1000건 요청 ≈ $0.03~0.14/일 팁: - system 프롬프트는 매번 입력 토큰에 포함됨 - 긴 대화 맥락은 비용 급증 주의 - Haiku로 먼저 테스트 후 Sonnet/Opus로 전환
401 Unauthorized → API Key 확인 (오타? 만료? 환경변수 로드됐나?) 400 Bad Request → JSON 구조 확인 (필수 필드 누락? 잘못된 모델명?) 429 Too Many Req → Rate Limit 초과, 잠시 후 재시도 (지수 백오프) 500 Server Error → Anthropic 서버 문제, status.anthropic.com 확인 408 Timeout → max_tokens 줄이거나 streaming 방식 전환 공통 디버깅 순서: 1. 상태 코드 확인 2. 에러 메시지 본문 읽기 3. API Key, 모델명, JSON 형식 순서로 점검 4. Anthropic 상태 페이지 확인 (status.anthropic.com)