에이전트가 비즈니스 상태를 변경할 때 안전한 MCP 패턴

AI 에이전트에게 실제 비즈니스 시스템에 대한 안전한 쓰기 권한을 부여하기 위한 세 가지 패턴을 보여주는 최소한의 MCP 서버: 단계 게이팅(phase-gating), 변경 전 검증(validation-before-mutation), 구조화된 감사 로깅(structured audit logging).

이것은 데모이지 제품이 아닙니다. 도메인(장난감 수준의 재고 + 구매 주문 시스템)은 패턴이 적용될 구체적인 대상을 제공하기 위해 존재할 뿐입니다 — 핵심은 패턴 자체이며, 패턴은 도메인에 구애받지 않습니다.

왜 이런 것이 필요한가

AI 에이전트는 점점 더 실제 시스템에 대한 쓰기 권한을 부여받고 있습니다 — 주문, 재고, CRM 레코드, 예측. 일반적인 실패 모드는 근본적인 LLM이 추상적인 의미에서 신뢰할 수 없다는 것이 아니라, 구현이 모델이 구조적 안전장치 없이 "올바른 일을 할 것"이라고 신뢰하는 경우가 많다는 점입니다. 에이전트가 상태를 환각하거나, 프롬프트 인젝션에 조종당하거나, 단순히 작업 순서를 잘못 이해하면, 그 결과는 인간이 사후에 발견하고, 진단하고, 수정해야 하는 조용한 잘못된 쓰기가 됩니다.

아래 세 가지 패턴은 새로운 연구가 아닙니다 — 프로덕션 상태를 다루는 모든 것에 적용되는 표준 엔지니어링 규율을 에이전트 도구 호출에 특별히 적용한 것입니다.

Related MCP server: commerce-ops-harness

세 가지 패턴

1. 단계 게이팅. 변경 작업(submit_purchase_order)은 동일한 세션에서 해당 읽기/미리보기 작업(draft_purchase_order)이 먼저 발생하지 않으면 성공할 수 없습니다. 이는 코드로 강제됩니다 — 모델이 무시하거나 설득으로 벗어날 수 있는 프롬프트 지시가 아니라 하드 오류입니다. 오류 메시지는 호출자에게 다음에 정확히 무엇을 해야 하는지 알려주며, 이것이 에이전트가 그냥 실패하는 대신 스스로 수정할 수 있게 하는 요소입니다.

2. 변경 전 검증. 모든 검사 — SKU가 존재하는지, 수량이 합리적인지, 합리적인 주문 임계값을 초과하지 않는지 — 는 아무것도 쓰기 전에 제안된 변경 사항의 순수한 표현에 대해 실행됩니다. 검증에는 부작용이 없습니다. 그리고 결정적으로: 모든 검사는 이전 검사가 실패했더라도 모두 실행되므로, 호출자는 하나를 고치고 다시 제출하고 다음 오류를 만나는 대신 모든 문제를 한 번에 볼 수 있습니다.

3. 구조화된 감사 로깅. 모든 도구 호출이 로깅됩니다 — 성공한 변경뿐만 아니라 차단되거나 거부된 호출도 포함됩니다. 거부된 시도를 기록하지 않는 감사 추적은 나중에 검토할 가치가 있는 정확히 그 이벤트, 즉 에이전트가 무엇을 시도했고 왜 중단되었는지를 놓치고 있는 것입니다.

데모

• examples/happy_path.md — 초안 → 검토 → 제출, 실제 캡처된 출력 포함

• examples/blocked_paths.md — 안전 계층이 잘못된 호출을 실제로 중단하는 다섯 가지 방법, 실제 출력 포함

직접 실행해 보기

pip install -r requirements.txt
pytest tests/ -v          # 17 tests, exercises every pattern above
python server.py          # runs the MCP server over stdio

테스트가 위의 설명보다 실제 증거입니다. 이 README의 주장을 검증하려면 해당 테스트가 제 설명보다 더 나은 진실의 원천입니다.

구조

server.py              # MCP tool definitions — thin, delegates everywhere
safety/
  phases.py             # session state + the phase gate itself
  validation.py         # pure validation functions
  audit.py               # structured logging, including failures
domain/
  inventory.py           # toy in-memory "database"
  purchase_orders.py    # draft/commit data + transformations
tests/                   # one file per pattern, ~17 tests total
examples/                 # real captured walkthroughs

safety/와 domain/은 "비즈니스 로직"과 "안전장치"의 분할이 뒤집힐 것이라는 예상과 달리 서로를 import하지 않습니다: 도메인 계층은 세션이나 승인의 존재를 알지 못합니다. 게이트는 전적으로 그 외부인 safety/phases.py에 있으며, domain.purchase_orders.commit_draft()에 도달할 수 있는지 여부를 결정합니다. 이러한 분리는 의도적입니다 — 재고 로직을 동시에 추론하지 않고도 안전 속성에 대해 추론할 수 있게 만드는 요소입니다.

이것이 아닌 것

프로덕션 코드가 아닙니다. 실제 데이터베이스가 없습니다 — 재고는 Python dict입니다. 인증이 없습니다. 세션 상태는 인메모리 단일 프로세스입니다. 이것은 안전 패턴을 독립적으로 검사하고 테스트할 수 있게 만들기 위해 존재하며, 누구나 배포해야 하는 시스템이 아닙니다.

배경

저는 Eli Lilly 인턴십 기간 동안 프로덕션 MCP 서버(Go, Kubernetes)를 설계하고 구축했으며, 단계 게이팅된 도구 액세스와 상태 변경 배포 작업 전 필수 검증을 포함했습니다. 이 데모는 다른 도메인에서 해당 코드를 전혀 사용하지 않고 새로 구축되었습니다 — 독점적인 것에 대한 접근 없이 읽고, 실행하고, 테스트할 수 있도록 동일한 기본 패턴을 분리한 것입니다.