Claude 2026 기능 전면 해석: API, Tool Use, MCP, Structured Output와 AI Agent

1. 기능 목록이 길수록 프로덕션은 더 잘 깨진다

2025년 말부터 2026년에 Anthropic은 「tool 호출」「MCP 연결」「JSON Schema 출력」을 Messages 주 경로로 옮겼다: output_config.format이 beta output_format을 대체; tool 정의에 strict: true로 문법 제약 샘플링이 인자를 유효하게 유지; 원격 MCP는 mcp_servers와 type: "mcp_toolset"으로 같은 요청에 실린다. 문서는 명확하다. 그런데 엔지니어링에서는 세 가지 일이 한 덩어리로 무너진다:

• 사람이 읽는 prose와 기계가 ingest하는 JSON을 스키마 없는 텍스트 blob에 한꺼번에;
• 로컬 스크립트, SaaS, 쓰기 가능 MCP tool을 하나의 tools 배열에 평탄화해 모델이 고르게;
• Agent를 「같은 user 턴을 20번 반복」으로만 정의하고 max step·tool_use 감사 없이.

데모는 된다; 티켓에는 JSONDecodeError, 잘못된 enum, MCP 서버를 만능 shell로 쓰는 사례가 쌓인다. Claude API가 「기능이 부족」한 게 아니다. 진입·실행·컨텍스트가 갈라지지 않았다. Agent가 xcodebuild를 돌려야 하면 실행은 실제 Mac 하드웨어에 닿는다——셀프호스트 GitHub Actions macOS runner와 같은 운영 문제이지 프롬프트 문제가 아니다.

2. 각 레이어가 무엇인가(What)

2.1 Claude API — 대화 진입점, Agent 제품이 아님

Claude API(Messages)는 모델, 메시지, system prompt, cache, 과금을 시스템에 붙이는 진입점이다. tool을 실행해 주지 않고 json.loads도 보장하지 않다. 채팅 완성으로 쓰는 것은 정당하다. 하류가 DB를 쓰고 티켓을 열고 CI를 트리거하는 순간 뒤 레이어를 쌓는다. 먼저 묻는다: 이 호출의 소비자는 사람인가 파서인가?

2.2 Tool Use — 자신이 소유하는 실행면

Tool Use는 모델이 tool_use 블록을 내고 서버가 실행한 뒤 tool_result를 돌려준다. 자체 구현용: 재고, 티켓, repo 스크립트. 2026 프로덕션에서는 정의에 strict tool use를 붙인다: strict: true와 input_schema가 Structured Output과 같은 문법 파이프라인을 써 「문자열 2를 숫자로」 같은 크래시를 줄인다. 대가: 스키마가 Anthropic이 지원하는 JSON Schema 부분집합에 맞아야 한다.

2.3 MCP 커넥터 — 원격 tool 면, 또 하나의 SDK가 아님

Messages MCP 커넥터는 원격 서버(URL, OAuth)와 mcp_toolset(전체, allowlist, denylist)을 선언한다. 발견과 전송을 해결한다: SaaS마다 Anthropic tool JSON을 손으로 쓰지 않는다. 자동으로 안전하지 않다——파일시스템·shell MCP는 게이트웨이나 allowlist가 필요하다. 프로토콜 「왜 USB」와 이 페이지의 「API에 서버를 매는 방법」은 보완 관계이지 중복 기사가 아니다.

2.4 Structured Output — 파서용 컨텍스트, 독자용 문체가 아님

Structured Output은 output_config.format의 json_schema로 모델 텍스트 블록을 유효 JSON으로 만든다. 필드 추출, 리포트 객체, 다음 서비스 계약용. Tool Use와 직교한다: JSON만, strict tool만, 둘 다. tool 호출 대체가 아니다——예쁜 JSON도 HTTP를 쏘지 않는다.

2.5 AI Agent — 루프 정책, 다섯 번째 API 제품이 아님

여기서 AI Agent는: 모델이 tool 고름 → 실행 → 결과 반환 → 멈출 때까지. 멈춤 조건은 자신이 쓴다: max round, 금지 tool 이름, 예산, 사람 확인. 루프는 Tool Use만 또는 MCP 혼합. Structured Output은 최종 인도에 맞다. 루프 상한 없는 「완전 자동」은 무한 재시도다.

3. 핵심 비교(How Compare)

4. 선택 방법(Decision)

소비자와 side effect를 먼저 고정한 뒤 레이어를 고른다. 매트릭스는 외부 상태를 바꾸는지로 갈린다.

5. 권장 스택

기능을 쌓는다. 단일 제품명을 찾지 말 것.

• 개인 스크립트 / 내부 봇: Claude API + 자체 tool 2–5개 + strict. secret 표면이 worth할 때까지 MCP 생략.
• 성장 중 SaaS 지원 Agent: 자체 쓰기 tool(티켓) + 읽기 전용 MCP 지식 + 끝에서 Structured Output으로 QA.
• 플랫폼 / 멀티 팀: 인증·rate limit용 MCP 게이트웨이; step·예산용 오케스트레이터; 과금 쓰기는 자체 Tool Use 유지.
• macOS / iOS 빌드 Agent: 「지정 runner에 job enqueue」만 노출; 실제 xcodebuild는 안정적인 cloud Mac에서, 모델 주도 ad-hoc SSH 아님.

IDE Skills 대비: API Agent는 시스템 side effect 루프를 갖고; Claude Code Skills는 repo 내 개발자 SOP를 갖는다. 둘 다 MCP를 말할 수 있지만 쓰기 권한 credential 테이블은 공유하지 말 것.

6. 흔한 실수

• 「MCP면 Tool Use를 버릴 수 있다」 → 쓰기 경로, 컴플라이언스, idempotency는 자체 소유·감사 유지.
• 「Structured Output이 Agent다」 → 텍스트 JSON만 제약; side effect 없음.
• 「strict는 아무 nested JSON Schema에서나 된다」 → 문서화된 부분집합 안에 머물기; 깊은 oneOf / 동적 key는 실패.
• 레거시 beta output_format과 output_config를 두 제품으로 취급 → 전환 호환만; 새 코드는 output_config.format.
• 「더 강한 모델은 max step 불필요」 → step은 돈과 blast radius 문제, IQ 아님.
• 모든 MCP 클라이언트 schema에 strict 복붙 → 일반 MCP 채널에서는 API 전용 필드 제거.

7. 일곱 단계 도입

1. side effect 목록: 읽기 query, 내부 쓰기, CI 트리거, 프로덕션. 클래스당 tool 테이블 하나.
2. 자체 tool 하나 배포: 최소 input_schema + strict: true; tool_use → 실행 → tool_result 검증.
3. 사람 vs 기계 전달 분리: 기계 계약은 Structured Output 또는 전용 parse 호출.
4. 읽기 전용 MCP 연결: mcp_servers + allowlist; 쓰기는 자체 유지.
5. 루프 감싸기: max N step, timeout, token 예산, 미선언 tool 이름 거부.
6. 관측: tool 이름, arg hash, latency, schema 실패 기록—최종 assistant 텍스트만 아님.
7. 무거운 실행 고정: macOS job은 cloud Mac / 셀프호스트 runner; Agent는 job id만 내고 노트북 shell 아님.

# Pseudocode — use the official SDK in production
POST /v1/messages
{
  "model": "claude-opus-4-6",
  "max_tokens": 2048,
  "tools": [{
    "name": "create_ticket",
    "strict": true,
    "input_schema": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "severity": {"type": "string", "enum": ["low","high"]}
      },
      "required": ["title","severity"],
      "additionalProperties": false
    }
  }],
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "ticket_id": {"type": "string"},
          "next_action": {"type": "string"}
        },
        "required": ["ticket_id","next_action"],
        "additionalProperties": false
      }
    }
  },
  "messages": [{"role": "user", "content": "높은 심각도 티켓 열기: 빌드 타임아웃"}]
}

모델 ID는 콘솔과 Tool Use 개요에 맞춘다. 프로덕션 전 output_config와 strict가 SDK 버전에서 leftover beta 헤더에 의존하지 않는지 확인.

8. 결론

Claude API는 모델을 시스템에 붙이는 방법.Tool Use는 자체 실행과 보장된 인자.MCP는 원격 발견과 trimming.Structured Output은 파서 계약.AI Agent는 루프가 멈추는 시점과 blast radius. 다섯은 병렬 「새 기능」 헤드라인이 아니다. 하나의 진입, 두 실행면, 하나의 전달 형식, 자신이 쓰는 오케스트레이션. side effect 경계를 먼저 그리고 MCP와 루프를 켜서 데모가 프로덕션을 버틴다.

더 읽기: Structured outputs · Strict tool use · MCP connector · MCP 프로토콜 입문