自作APIをMCPサーバー化するハンズオン講座を作った日。FastAPIミニ仕訳帳APIの実装と検証セッションの記録

午前、MCPと生のAPIは結局何が違うのかを整理していた。会計ソフトBの公式MCPサーバーを読んだ解剖記事で構造は見えたが、他人のコードを読んだだけの理解は、自分で書いた理解より一段浅い。

それなら、ミニマムな自作APIを作って、それをMCPサーバー化するまでの一連の流れをハンズオン講座にしてしまおうと決めた。読者は税理士・会計士。手を動かせば「MCPで包むと何が変わるか」を自分の端末で確かめられる教材にする。

計画書レビュー4往復からマルチエージェント実装へ

計画書を書いてCodexレビューに出した。4往復して承認になったところで、ultracode（マルチエージェントのワークフロー）にmdx-playgroundでの実装を任せた。成果物は2つ。

教材リポジトリ journal-mcp-tutorial（別リポジトリ）: FastAPI製のミニ仕訳帳API（3エンドポイント）と、それを包むMCPサーバー
講座記事自作APIをMCP化するハンズオン: 写経→実行→比較まで通しでやる本体

実装の途中では、バリデータの raise のインデントミスで「どんな入力でも422を返す」状態が混入しかけたが、ワークフロー内のセルフチェックで拾われて修正された。

テスト前に潰れたのを実装ログで確認できたのは安心材料だった。教材のコードは読者が写経する。バグ入りのまま公開したら、講座そのものが成り立たない。

ミニ仕訳帳APIの中身

認証は X-API-Key ヘッダー。キーは環境変数 JOURNAL_API_KEY に置き、値は会話にもコマンド出力にも書き出さない前提で講座全体を組んだ。勘定科目はホワイトリスト制で、使えるのは7科目だけ。

ALLOWED_ACCOUNTS = {"現金", "普通預金", "買掛金", "資本金", "売上高", "仕入高", "消耗品費"}

わざと小さく作った。科目を絞ると、正常系だけでなく「使えない科目を頼まれたときにエージェントがどう止まるか」まで教材にできる。

検証セッションを何度も回した

書きっぱなしにせず、クリーンなセッションを立てては同じ依頼文を投げる再現テストを繰り返した。経路は2つ。

素のAPI直叩き: 「http://127.0.0.1:8000 でミニ仕訳帳APIが動いている。リファレンスは /docs、機械可読版は /openapi.json」とだけ渡して仕訳登録を頼む
MCPツール（journal）経由: 「仕訳の操作はこのツールで」とだけ渡して、同じ仕訳登録を頼む

依頼文も2種類用意した。

「2026-07-25付で消耗品費 3,300円を現金で支払った」→ 両経路とも通った。APIは HTTP 201 を返して id 6 が付いた
「2026-07-26付で雑費 1,200円を現金で支払った」→ 両経路とも同じ場所で手が止まった。雑費はホワイトリスト外だからだ

止まり方も観察した。素のAPI直叩きでは /openapi.json を読んで「この科目は使えないので未実行。どうするか判断がほしい」と返してきて、MCP経由でも使える7科目を列挙して判断を仰いできた。

成功だけでなく止まり方まで両経路で一致したのを見て、比較教材として成立したと手応えを得た。

MCP経由の1回は、ツールの実行許可プロンプトで登録が保留になった。生のAPIならcurlが即座に走る場面で、MCPだと承認が一段挟まる。この差もそのまま講座の比較ポイントに使える。

仕上げに「このチュートリアル、読んで実行するだけで本当に全部通るのか」と聞いて、ultracodeに実地検証させた。それまでの再現テストは写経部分（Step 1〜4）だけだったので、Before/Afterのエージェント実験（claude -p）まで含めて、記事に書いたコマンドだけで最後まで通ることを確かめさせた。

タイトルから「事故の構造」を外した

講座記事の初稿タイトルには「差は能力ではなく事故の構造だった」と入っていた。最初「自己の構造」と読み、どういう意味かと問い詰めてから気づいた。読み手も同じところでつまずく。

そもそもこれはハンズオン記事で、読者への約束は「手を動かすと何ができるか」のはずだ。実験レポートの結論をタイトルに置く必要があるのかと聞くと、タイトル案が並び、「自作APIをMCP化するハンズオン。ミニ仕訳帳APIを作り、生のまま使い、包んでから使って比べる」に差し替えさせた。

分析の言葉は本文の差分表まわりに説明つきで残すだけにした。タイトルの回収文とfrontmatterも合わせて直させ、dev環境での描画まで確認済みの状態で受け取った。

ディレクトリ構造がそのまま「出来上がりイメージ」になった

教材リポジトリのファイル構成を全部見せてほしいと頼んで眺めていたら、これは講座の「出来上がりイメージ」そのものだと気づいた。写経を始める前に完成形の地図があれば、いまどこを作っているのかを見失わない。

そこで講座記事の準備セクション直後に、ファイル構成の全体図を「どのStepでどのファイルが増えるか」の対応つきで載せさせた。単発の追記なのでワークフローは使わず、直接編集で済ませた。

コード表示を読めるようにする

講座記事のコードブロックには「PYTHON · api.py」形式のヘッダーを入れさせた。いまどのファイルを写経しているのかが、ブロックを見た瞬間に分かる。

SSRにファイル名が出ないという小さな詰まりがあったが、パース結果（SQLiteのAST）に filename が入っているかを直接確認させて、9ブロック全部に反映された。今後どの記事でも使える汎用の対応になった。

夕方には、学習ゲートのクイズにコード例を出せるようにする改修のついでに、コード表示がハイライト無しの単色で目が滑るのが気になった。mdx-playgroundではなくeurekapu-nuxt4側にハイライトの実装があるはずだと伝えて、同等のものを移植させた。

色が付いただけで、どこがキーワードでどこが文字列かを探す時間が消えた。

分割コミットと学習ゲート

1日の締めに、リポジトリの未コミット変更（変更26ファイル＋新規約130ファイル）を棚卸しさせ、依存順（コード→コンテンツ→設定・メモ）で14コミットに分割した。コミット後の git status がクリーンで、取り残しゼロも確認できた。

学習ゲートのクイズは、この日は回答の時間が取れず全コミットでスキップにした。回避ではなく正規の手順（LEARN_SKIP=1＋理由の記録）で通してあり、スキップした事実はログに残っている。

残タスク

教材リポジトリのGitHubプライベートリポジトリ作成（承認待ちのまま持ち越し）

学び

教材APIはわざと小さく作ると「止まり方」まで教材になる。科目ホワイトリスト7個がいい仕事をした
検証は「素のAPI直叩き / MCP経由」の2経路 ×「通る依頼 / 止まる依頼」の2依頼文で回すと、比較の主張に実測の裏が付く
ハンズオン記事のタイトルは「何をやる講座か」を先に約束する。分析の結論は本文で回収すればいい
APIキーは環境変数に置き「値を出力に書き出さない」縛りを依頼文に入れると、エージェント側もその縛りを守って動く。講座でもこの形を既定にした