Claude CodeでMCPサーバーを構築する方法：ステップバイステップガイド（2026年）

· 執筆：Jasmine — Claude Codeを毎日使い、チーム向けに社内MCPサーバーをいくつか手書きしてリリースしてきた開発者です。

MCPサーバーとは？（簡単なおさらい）

MCPサーバーとは、3種類の機能——ツール（エージェントが呼び出せる関数）、リソース（読み取れるデータ）、プロンプト（再利用可能なプロンプトテンプレート）——を、Model Context Protocol を通じてLLMに公開する小さなプロセスです。 言い換えれば、Claude Codeと外部世界——社内API、データベース、ファイルシステム、あるいはClaudeに制御された形で接続させたいあらゆるサービス——との標準化された「アダプター」です。

MCPの優れた点は、オープン標準であることです。サーバーを一度書けば、多くのホスト（Claude Code、Claude Desktop、その他のクライアント）で使えます。このガイドでは概念を深掘りしません——それはMCPとはの記事で扱います。ここでは、公式ドキュメントが通常バラバラに扱っている部分、つまり自分でサーバーを書き、それをそのままClaude Codeに接続することに焦点を当てます。

自分でMCPサーバーを書く必要が本当にあるのはいつか？

コードを1行書く前に、こう問いましょう。このサーバーはすでに誰かが書いていないか？ よくあるニーズの多くには、すでに公式またはコミュニティのサーバーがあります——GitHub、Playwright、Sentry、ファイルシステムなどです。既存のものを接続する方が、新しく作るより常に速いです。

私の経験則はこうです。データやロジックが自分のもので、まだ標準的なアダプターが存在しない場合に、自分でMCPサーバーを書く。他の人がすでにうまくやっていることを書き直さないこと。

始める前に

途中でつまずかないための短いチェックリストです。

• Claude Codeがインストール済みでサインインしていること（Pro/MaxプランまたはAPIキーのどちらでも動きます）。
• ランタイム：Node.js 18+（TypeScriptの場合）またはPython 3.10+（Pythonの場合）。
• SDKを選ぶ：Pythonが得意ならFastMCP／Python SDK、Nodeで暮らしているなら TypeScript SDK（@modelcontextprotocol/sdk）。
• 具体的なゴール：たとえば「社内APIから注文を検索するツール」。何でもできる汎用サーバーから始めないこと。

Claude Codeが初めてなら、まずClaude Codeとはを読んで、セッションの実行方法と権限の付与方法を理解してください。

オプション1 — MCPサーバーを手書きする

一度手作業でやってみると、Claudeがツールを呼び出すときに実際に何が起きているかを理解できます。その後は自由に自動化できます。以下の5つのステップで、設計から動作するテストまでを進めます。

ステップ1 — エンドポイントではなくワークフローを中心にツールを設計する

最もよくある間違いは、各RESTエンドポイントを1対1でツールに対応させることです。その結果、1つのことをするのに5つのツールを呼ばなければならないエージェントができ、簡単に筋道を見失います。代わりにエージェント中心で設計しましょう。

• 意図ごとに操作をまとめる：エージェントにget_order + get_customer + get_itemsをつなぎ合わせさせる代わりに、1つのget_order_summaryツールで一度にすべてを返します。
• 人間やエージェントが読める出力を返す：内部コードではなく、分かりやすいフィールド名を使います。
• エージェントに「教える」エラーメッセージを書く：スタックトレースだけでなく、修正のヒントを添えてエラーを報告します。

これらの原則は、ak-mcp-builderスキルに組み込まれたベストプラクティスに由来します——多くの汎用チュートリアルが省略している部分です。

ステップ2 — プロジェクトをスキャフォールドしてSDKをインストールする

後で分かりやすいように、名前は明確に付けましょう。Pythonでは{service}_mcp、TypeScriptでは{service}-mcp-serverを使います。

Python（FastMCP）：

python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "mcp[cli]" # or: pip install fastmcp

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders_mcp")

if __name__ == "__main__":
 mcp.run() # defaults to the stdio transport

TypeScript（MCP SDK）：

npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "orders-mcp-server", version: "1.0.0" });

const transport = new StdioServerTransport();
await server.connect(transport);

ステップ3 — 最初のツールを書く（実行可能な例つき）

良いツールには3つの要素があります。厳密な入力スキーマ、明確な説明（エージェントはこれを読んでツールをいつ呼ぶか判断します）、そして振る舞いを記述するツールアノテーションです。以下は注文検索ツールです。

Python：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders_mcp")

@mcp.tool(
 annotations={
 "readOnlyHint": True, # read-only, does not change data
 "idempotentHint": True, # same result when called again
 "openWorldHint": True, # calls an external system
 }
)
def get_order_summary(order_id: str) -> str:
 """Look up a summary of one order by its order ID.
 Use when the user asks about the status/total/customer of a specific order."""
 order = fetch_order(order_id) # calls your internal API
 if order is None:
 return f"Order '{order_id}' not found. Double-check the ID (format ORD-xxxxx)."
 return (
 f"Order {order['id']} | Customer: {order['customer']} | "
 f"Status: {order['status']} | Total: ${order['total']:,}"
 )

TypeScript（入力スキーマにZodを使用）：

import { z } from "zod";

server.registerTool(
 "get_order_summary",
 {
 description: "Look up a summary of one order by its order ID.",
 inputSchema: { order_id: z.string().describe("Order ID, format ORD-xxxxx") },
 annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
 },
 async ({ order_id }) => {
 const order = await fetchOrder(order_id);
 const text = order
 ? `Order ${order.id} | Customer: ${order.customer} | Status: ${order.status}`
 : `Order '${order_id}' not found.`;
 return { content: [{ type: "text", text }] };
 }
);

Claudeがツールを呼び出したときのサンプル出力：Order ORD-10231 | Customer: Alex Nguyen | Status: In transit | Total: $540。1つ注意点があります。アノテーションはホストにとってヒントにすぎず、セキュリティの仕組みではありません——書き込みをブロックするためにreadOnlyHintに頼ってはいけません。

ステップ4 — トランスポートを選ぶ（stdio / HTTP / SSE）

トランスポートは、ホストがサーバーとどう通信するかを決めます。何となくデフォルトにするのではなく、状況に応じて選びましょう。

ローカル＋Claude Codeのデフォルト：stdioを使う。サーバーを複数人で共有したり、リモートにデプロイしたりする必要があるときだけHTTPに移行します。

ステップ5 — 正しいやり方で実行してテストする

ここで多くの人がつまずきます——そしてそれを警告するチュートリアルはほとんどありません。

• サーバーは長時間動き続けるプロセスです。python server.pyを直接実行すると、stdio経由の入力を待っているためターミナルが「フリーズ」したように見えます——これは正常で、バグではありません。詰まらずにサッと確認するには、timeout 5s python server.pyを使うか、tmux／別のペインで実行するか、評価用ハーネスを使いましょう。
• stdioでは、絶対にstdoutにログを出さない。stdoutはプロトコルのチャネルです——そこに紛れ込んだprint()はJSON-RPCストリームを壊し、サーバーは分かりにくい形で「死に」ます。代わりにstderrにログを出しましょう（Python：print(..., file=sys.stderr)またはloggingモジュール）。
• まずコンパイルできることを確認する：Pythonはpython -m py_compile server.py、TypeScriptはnpm run build。

最も信頼できるテスト方法は評価駆動（eval-driven）です。各ツールをサンプル入力で呼び出して出力をアサートするスクリプトを書き、timeout付きの子プロセスで実行します。そうすれば、Claude Codeに接続してから何も返さないツールに気づく代わりに、スキーマやプロトコルのバグをすぐに捕まえられます。

オプション2 — Claude CodeにMCPサーバーを書いてもらう

オプション1で構造を理解したら、毎回ボイラープレートを打ち直す必要はありません。これが面白い「メタな視点」です。Claude Code自身を使って、Claude Code用のMCPサーバーを書くのです。

エージェントがタスクから外れないように分割した、私のお気に入りのプロンプトパターンです。

Write a Python MCP server named orders_mcp using FastMCP.
- Tool get_order_summary(order_id) calls our internal API at BASE_URL (read from env).
- Tight input schema, clear description, readOnlyHint/idempotentHint annotations.
- Log to stderr, NOT stdout. Transport stdio.
Then write a test script that uses timeout so it does not hang, and explain how to wire it into Claude Code.

Claude Codeはプロジェクトをスキャフォールドし、ツールとスキーマを書き、頼めばテストのステップも書いてくれます。あなたの主な仕事はそれをレビューすることです——繰り返しの部分はエージェントが処理します。ヒント：書き始める前にエージェントに前提（パス、環境変数名）を述べさせ、その場のセッションでpy_compile／npm run buildを自分で実行させてコードがコンパイルできることを確認させましょう。そうすれば、テストされていないコードの山ではなく、すでに基本的なチェックを通ったサーバーが手に入ります。

サーバーを数多く作るなら、すべてのベストプラクティスを自分で覚える代わりに、既製のスキルを使う価値があります。AgentKit（ak-mcp-builderスキル）のEngineer Kitは、多段階のMCPサーバー構築プロセス（research -> implement -> review -> eval）を提供し、ツール設計のベストプラクティスとテスト用の評価ハーネスをパッケージ化しています——だから、上記のボイラープレートやstdio／長時間プロセスの罠をすべて頭に入れておく必要はありません。詳しくはAgentKitのEngineer Kitの中身をご覧ください。

混同を避けるための補足：ここでの「AgentKit」はClaude Code向けのスキル群（agentkit.best、ak CLI）を指し、OpenAIの「AgentKit」製品とは別物です。私のやり方：理解のために一度手作業でやり、その後はスピードのためにスキルを使う。

MCPサーバーをClaude Codeに接続する

サーバーができたので、Claude Codeに接続しましょう。中心となるコマンドはclaude mcp addです。

ローカルのstdioサーバー——--区切りの後にコマンドを渡します。

claude mcp add orders -- python /path/to/server.py
# or a built TypeScript server:
claude mcp add orders -- node /path/to/dist/index.js

リモートサーバー（HTTP）：

claude mcp add orders --transport http https://mcp.company.com/orders

接続を確認します。

claude mcp list # shows: orders ✔ Connected
claude mcp get orders # view a server's full configuration

スコープは、サーバーがどこで利用できるかを決めます。local（自分だけ、このプロジェクトのみ）、project（チーム全体のためにコミット）、user（自分のすべてのプロジェクト）。チームで共有するサーバーの場合は、リポジトリのルートに.mcp.jsonを手書きしてコミットします。

{
 "mcpServers": {
 "orders": {
 "command": "python",
 "args": ["server.py"],
 "env": { "BASE_URL": "https://api.internal.company.com" }
 }
 }
}

.mcp.jsonを編集した後は、再読み込みのためにClaude Codeのセッションを再起動することを忘れないでください。

よくある問題とその解決方法

MCPサーバーを書くためのベストプラクティス

覚えておく価値のあることをまとめます（多くはak-mcp-builderに由来します）。

• ツールに名前を付けるには{service}_{action}_{resource}パターン（snake_case）を使い、複数のサーバーを接続したときの衝突を避けるためにサービスのプレフィックスを付けます。
• 出力にはJSONとMarkdownの両方をサポートする——エージェントは構造化データをよく読み、人間はMarkdown版の方が読みやすいです。
• 大量のデータを返すツールはページネーションする：何千行も返す代わりにlimit、has_more、next_offsetを使います。
• 出力の長さに上限を設ける（経験則で約25,000文字）、そしてガイダンス付きで切り詰める（「あとN件、offsetを使って...」）。
• エラーメッセージを実用的にする：何が問題で、どう直すかを正確に伝えます。
• セキュリティ：入力を検証し、APIキーは環境変数に保持し（ハードコードしない）、内部エラーやスタックトレースをエージェントに漏らさないこと。アノテーションはヒントにすぎず、本物のアクセス制御の代わりにはならないことを忘れないでください。

開発ワークフローをもっと自動化したいですか？ Claude Code用のカスタムスキルを作る方法や、Claude Codeのサブエージェントを使ってビルド／テストの作業を分担する方法をご覧ください。

よくある質問（FAQ）

MCPサーバーはどの言語で書くべきですか？

最も一般的な選択肢は Python（FastMCP／Python SDK）と TypeScript（@modelcontextprotocol/sdk）です。MCPには他の言語のSDKもありますが、Claude Codeには、Python か TS が最も速く、例も最も多い選択肢です。

既存のサーバーに接続するのとどう違いますか？

既存のサーバーに接続するには、誰かがすでに書いたものにclaude mcp addを向けるだけです。自分でサーバーを書くのは、まだ誰もアダプターを作っていない自分のロジックやデータ（社内API、DB）を公開する必要があるときです。

Claude Codeは自分でMCPサーバーを書けますか？

はい。欲しいツール、スキーマ、トランスポートを説明すれば、Claude Codeがプロジェクトをスキャフォールドし、ツールを書き、テストスクリプトまで書いてくれます。あなたはそれをレビューするだけです。ak-mcp-builderスキルは、このプロセスをベストプラクティスとともにパッケージ化しています。

リモート（HTTP）サーバーはどうやってデプロイしますか？

自前のインフラでstreamable HTTPトランスポートを使ってサーバーを実行し、次にclaude mcp add <name> --transport http <url>とします。リモートサーバーは認証（OAuth／トークン）も扱う必要があります——自分のマシンを信頼するローカルのstdioサーバーとは違います。

Claude Code Proは必要ですか？

特定のプランは必要ありません。サインインすればMCPはClaude Codeで動きます——Pro/MaxプランでもAPIキーでも動きます。サーバーを書くこと自体には、すでに支払っているモデルの利用料以外の費用はかかりません。

ak-mcp-builderとは何ですか、そして必須ですか？

ak-mcp-builderは、評価ハーネスを備えた多段階プロセスでMCPサーバーを構築する、AgentKitのEngineer Kitのスキルです。必須ではありません——オプション1のようにすべて手書きできます。数多くのサーバーを作るときに、作業を速くし、ベストプラクティスの罠を避けるのに役立つだけです。

まとめと次のステップ

おさらいすると、Claude CodeでMCPサーバーを作る方法は2つあります。深く理解するために手書きする（ワークフローを中心にツールを設計 -> SDKをインストール -> ツールを書く -> トランスポートを選ぶ -> timeout／stderrでテスト）方法と、スピードが必要なときにClaude Codeに書いてもらう方法です。どちらの場合も、要はclaude mcp addまたは.mcp.jsonでClaude Codeに接続し、✔ Connectedを確認することです。私のアドバイス：理解のために一度手書きし、それから自動化しましょう。

次のステップとして、この構築プロセスを自分のカスタムスキルにしてみましょう。そして、標準化された評価対応済みのMCPサーバー構築プロセスをそのまま使いたいなら、AgentKitのEngineer Kit — 20％オフ、現在79.20ドル（ak-mcp-builderスキル）をチェックしてください。

出典：Model Context Protocol - 仕様＆サーバー構築ガイド（バージョン2026-07-28）；Claude Codeドキュメント - MCP＆claude mcp add（v2.1.219）。CLIは頻繁に更新されるため、使用前に正確なコマンドを確認してください。