SaaS公式MCPサーバーをリリースして得た学び

• URL: https://zenn.dev/lapras_inc/articles/lapras-mcp-server
• 日付: 2026-06-26
• Tier: Tier 3
• 要旨: エンジニア向けポートフォリオ・転職サービス LAPRAS が公式 MCP サーバーをリリースし、その設計判断と開発で得た失敗の学びをまとめた記事。公式 TypeScript SDK のみを採用して将来の仕様変更への追従性を確保し、tool 定義をファイル分離することでテストと拡張性を高める設計を採った。コンテキスト長の制限による API 失敗、複雑な API インターフェイスによる LLM の誤操作でデータが消える問題、LLM が改行をエスケープした文字列を出力してしまう問題など、MCP サーバー固有のハマりどころが詳述されている。更新系 tool の提供ではサービスとしてどこまで品質を担保するかという設計上の問いも生じている。

詳細

開発時の判断と理由:

• 公式 TypeScript SDK のみ採用: fastmcp 等のサードパーティ製は将来の仕様変更追従リスクがあるため
• リモート MCP は不採用: 採用例が少なく認証構築に工数がかかるため。現在なら Streamable HTTP Transport で検討の余地あり
• tool 定義をファイル分離: index.ts で一括登録する設計で、個別テストと新 tool 追加が容易になった

監視体制:

• MCP 専用 API を新規作成（既存 API と分離）
• AWS WAF でエンドポイントごとのレートリミット設定
• Datadog で MCP 用 API のリクエスト監視・アラート設定

開発中の失敗と対処:

1. コンテキスト長の問題: 大量データを返す tool が Claude Desktop 無料版（コンテキスト制限あり）でのみ失敗。per_page 縮小・不要フィールド除外で対処
2. 複雑な API インターフェイスによるデータ消失: バルク create/delete/update という一般的でない API を踏襲したところ LLM が意図せぬ削除を実行。force: true ガードを試みたが LLM が確認なしに指定してしまい断念。素直な部分更新 API に変更して解決
3. LLM 出力の改行エスケープ問題: LLM がパラメーターに \n を含めてしまい表示が崩れた。MCP サーバー側でクレンジング処理を追加して対応

設計上の議論:

• 更新系 tool では仕様的バリデーションは API 側で行えるが、内容の正当性は担保不可能
• 修正できる操作（職歴更新等）はリスクを取ってリリース。やり直しの効かない操作（応募・メッセージ送信等）は慎重に判断すべき