ビジネス状態を変更するエージェントのための安全なMCPパターン

AIエージェントに実ビジネスシステムへの安全な書き込みアクセスを提供するための3つのパターンを示す、最小限のMCPサーバーです: フェーズゲーティング、変更前検証、構造化監査ログ。

これはデモであり、製品ではありません。ドメイン(おもちゃの在庫+発注システム)は、パターンに具体的な適用対象を与えるためだけに存在します — パターン自体が本題であり、ドメインに依存しません。

これが存在する理由

AIエージェントには、注文、在庫、CRMレコード、予測など、実システムへの書き込みアクセスがますます与えられています。一般的な失敗モードは、基盤となるLLMが抽象的な意味で信頼できないということではなく、実装が構造的なガードレールなしにモデルが「正しいことをする」と信頼しがちだということです。エージェントが状態を幻覚したり、プロンプトインジェクションに操作されたり、単に操作の順序を間違えたりすると、その結果はシステムへの静かな誤書き込みとなり、人間が後から気づき、診断し、修正しなければなりません。

以下の3つのパターンは新しい研究ではありません — 本番状態に触れるものに対する標準的なエンジニアリング規律を、エージェントのツール呼び出しに特化して適用したものです。

Related MCP server: commerce-ops-harness

3つのパターン

1. フェーズゲーティング。 変更操作(submit_purchase_order)は、対応する読み取り/プレビュー操作(draft_purchase_order)が同じセッションで先に実行されない限り成功できません。これはコードで強制されます — モデルが無視したり説得されたりできるプロンプト指示ではなく、ハードエラーです。エラーメッセージは呼び出し元に次に何をすべきかを正確に伝えるため、エージェントは単に失敗するのではなく自己修正できます。

2. 変更前検証。 すべてのチェック — SKUが存在するか、数量が妥当か、妥当な注文しきい値を超えていないか — は、何かを書き込む前に、提案された変更の純粋な表現に対して実行されます。検証には副作用がありません。そして重要なことに: すべてのチェックは以前の失敗に関係なく実行されるため、呼び出し元は1つ修正して再送信して次の問題に当たるのではなく、すべての問題を一度に確認できます。

3. 構造化監査ログ。 すべてのツール呼び出しがログに記録されます — 成功した変更だけでなく、ブロックされたものや拒否されたものも含みます。拒否された試みについて沈黙している監査証跡は、後でレビューする価値があるまさにそのイベント — エージェントが何を試みて止められたのか、そしてその理由 — を欠いていることになります。

デモ

• examples/happy_path.md — ドラフト → レビュー → 送信、実際のキャプチャ出力付き

• examples/blocked_paths.md — セーフティレイヤーが不正な呼び出しを実際に止める5つの方法、こちらも実際の出力付き

自分で試す

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/ は、「ビジネスロジック」と「ガードレール」の分割が逆転するという期待する方向では互いにインポートしません: ドメインレイヤーはセッションや承認の存在を知りません。ゲートは完全にその外側、safety/phases.py に存在し、domain.purchase_orders.commit_draft() に到達するかどうかを決定します。この分離は意図的です — 在庫ロジックを同時に推論することなく、セーフティプロパティについて推論することを可能にします。

これは何ではないか

本番コードではありません。実際のデータベースはありません — 在庫はPythonのdictです。認証もありません。セッション状態はインメモリでシングルプロセスです。これはセーフティパターンを分離して検査・テスト可能にするために存在するのであり、誰かがデプロイすべきシステムではありません。

背景

私はEli Lillyでのインターンシップ中に、本番用MCPサーバー(Go、Kubernetes)を設計・構築しました。フェーズゲーティングされたツールアクセスと、状態を変更するデプロイ操作の前の必須検証を含みます。このデモは、そのコードを一切使わず、異なるドメインで新規に構築されています — 同じ基盤パターンを分離して、独自のものにアクセスせずに読んだり、実行したり、テストしたりできるようにしています。