Claude Codeに外部APIやデータベースを直接つなぐ「MCPサーバー」の自作方法を、PythonとTypeScriptの両方で解説します。3大プリミティブの使い分けから設定スコープの管理、トークン浪費を防ぐベストプラクティスまで網羅しています。
「MCPサーバーって何ができるの？」「Toolsしか使ってないけど大丈夫？」——MCPの本当の力を引き出すには、3つのプリミティブの理解と正しい設計が不可欠です。
この記事を読むと、Claude Code用のカスタムMCPサーバーをゼロから構築し、安全に運用するための全手順がわかります。
Claude Codeを自律型エージェントに変える「MCP」の革新性
MCPとは何か？なぜ革命的なのか
MCP（Model Context Protocol）はAnthropicが策定したオープンスタンダードです。AIモデルと外部ツール・データソースをJSON-RPCベースの共通プロトコルで接続します。通信のトランスポート層にはローカル向けのstdioとリモート向けのHTTP/SSEが用意されています。
従来はAPIごとに独自の連携コードをハードコードする必要がありました。MCPの登場により、一度サーバーを作ればClaude Code・Claude Desktop・Cursorなど任意のMCP対応クライアントから使い回せるようになりました。
Claude CodeのCLIから社内データベース（PostgreSQL等）、JIRA、GitHub、社内Wikiなどを直接操作・横断する「Agentic Workflow」が実現します。
多くのエンジニアが見落とすMCPの「3大プリミティブ」
MCPの機能をToolsだけで使っていませんか？専門家の分析によれば、それはMCPの潜在能力の10%しか活用していないのと同じです。
| 機能 | 役割 | 制御主体 | ユースケース |
|---|---|---|---|
| Tools | 副作用を伴うアクション（DB書き込み、API呼び出し等） | LLM | JIRAチケット作成、PR生成 |
| Resources | 読み取り専用データソース | アプリ | APIドキュメント、DBスキーマ参照 |
| Prompts | ツールチェーンをテンプレート化する指示書 | ユーザー | /analyze-codeで分析パイプライン起動 |
特にPromptsは、チーム全体で最適化されたAI操作手順（ADWs）を共有し、属人性を排除するゲームチェンジャーです。LLMのハルシネーションを抑制し、再現性の高い出力を得るための最重要機能といえます。
Python vs TypeScript：開発言語の選び方
| 項目 | Python | TypeScript |
|---|---|---|
| 推奨ツール | uv + fastmcp | @modelcontextprotocol/sdk + Zod |
| セットアップ | uv run mcp install main.py で即完了 |
npm init + SDK v1.x インストール |
| 強み | データ分析・ML連携 | 厳格な型検証・API連携の堅牢性 |
| 適したケース | Pandas等の既存ライブラリ活用 | 本番環境の型安全なサーバー |
Python環境ではuv run mcp install main.pyだけでClaude Desktopへの登録が完了する、極めて洗練された開発体験が提供されています。TypeScript環境ではZodでスキーマを定義しJSON Schemaに変換することで、LLMからの不正な入力を未然に防げます。
Claude Code CLIへの統合と設定スコープ管理
構築したサーバーはclaude mcp add-json <name> <json>コマンドでClaude Codeに登録します。--scopeフラグでサーバー構成の格納先を制御できます。
重要なのは4つの設定スコープの使い分けです。
| スコープ | 保存場所 | 用途 |
|---|---|---|
| Managed | OSシステムディレクトリ | 企業IT部門が全社統一で強制デプロイ |
| User | ~/.claude.json | 全プロジェクト共通の個人設定 |
| Project | .mcp.json | Git共有。チーム全員が同じツールセット |
| Local | ~/.claude.json（プロジェクト別） | APIキー等の機密情報用オーバーライド |
ベストプラクティス
スコープの優先順位はManaged→Local→Project→Userの順でマージされます。チーム開発ではProjectスコープの.mcp.jsonをGitで共有し、機密情報はLocalに分離しましょう。
知らないとハマる！MCPサーバー運用の致命的な罠
stdoutへのログ出力でプロトコルが壊れる
stdio通信では標準出力がJSON-RPCの専用チャネル
Pythonのprint()やNode.jsのconsole.log()でデバッグログを出すと、JSON-RPCパケットが汚染され通信が即座に破壊されます。ログは必ずsys.stderrまたはconsole.error()に出力してください。
トークンの浪費とコンテキスト圧迫
MCPサーバーをグローバルに大量接続すると、毎ターン30以上のツールスキーマ定義がモデルに送信され続けます。これはトークン消費の爆発、推論精度の低下、レスポンス速度の劣化を招きます。
グローバル（User）スコープへの無秩序な登録を避けます。
複数タスクを1回の呼び出しにまとめ、トークン消費を最大74%削減できます。
localhost:5173で起動し、LLMを介さずサーバーの単体テストが可能です。
まとめ：MCPで実現する次世代の開発体験
MCPサーバーの自作は、単なるAPIラッパーの作成ではなく、Claude Codeをシステムのオーケストレーターに据える戦略的投資です。
実践のポイント
・3大プリミティブを理解する——Toolsだけでなく、ResourcesとPromptsを活用
・設定スコープを正しく管理する——Projectで共有、Localで機密分離
・運用の罠を回避する——stdout禁止、スコープ制限でトークン節約
Promptsを活用した複雑なツールチェーンの自動化が、エンジニアリングチーム全体の生産性を飛躍させる鍵です。
コメント