Claudeが実際に呼び出すMCPサーバーは、約15分で構築できます。Node 20とPython 3.11で計測したところ、stdio上で動作しClaude Desktopに検出される機能するaddツールは、初回で14分、仕組みを理解すれば5分以内で完成しました。このチュートリアルでは、同じサーバーを2回構築します。一度はFastMCP 2.xを使用したPythonで、もう一度は@modelcontextprotocol/sdk 1.xを使用したTypeScriptです。これにより、自分のスタックを選んで実際のコードをコピーできるようになります。アーキテクチャやプロトコルの理論を先に知りたい場合は、Model Context Protocol概念ガイドをご覧ください。ここでは実装に焦点を当てます。
MCPサーバークイックスタート：何を作るのか
MCPサーバーは、Model Context Protocol経由でClaude、Cursor、VS CodeなどのAIクライアントにツール、データ、プロンプトテンプレートを公開する小さなプログラムです。サーバーを一度作成すれば、MCP互換のあらゆるクライアントから呼び出すことができます。このチュートリアルでは、2つのツール（add計算機とfetch_urlヘルパー）を持つサーバーを構築し、ローカルでstdio経由で実行、テストを行い、実際のクライアントに接続します。
開始前に必要なものは以下の通りです。
| 要件 | Pythonパス | TypeScriptパス |
|---|---|---|
| ランタイム | Python 3.10+（3.11推奨） | Node.js 20 LTS+ |
| パッケージマネージャー | uv（推奨）またはpip | npm、pnpm、またはbun |
| SDK | mcp 1.x / FastMCP 2.x | @modelcontextprotocol/sdk 1.x |
| テスト用クライアント | Claude Desktop、Claude Code、またはCursor | 同上 |
| テストツール | npx @modelcontextprotocol/inspector | 同上 |
どちらのパスでも、動作は同一のサーバーが作成されます。チームがすでに採用している言語を選んでください。 preferenceがない場合は、FastMCPを使えば最初のサーバーをより短く書けるため、Pythonから始めることをお勧めします。
MCPサーバーが実際に公開するものとは？
コードを書く前に、サーバーが提供できる3つの要素を知っておくと役立ちます。MCPサーバーは、ツール（モデルが呼び出せる関数。「データベースを検索」など）、リソース（モデルが読み込める読み取り専用データ。ファイルやレコードなど）、プロンプト（再利用可能なプロンプトテンプレート）を公開します。構築するほとんどのサーバーはツール中心となり、リソースとプロンプトはオプションです。
MCPサーバーの定義: Model Context Protocolを話し、AIクライアントがランタイム時に発見して呼び出すことができるツール、リソース、プロンプトのリストを広告するプロセス。
クライアント（例：Claude Desktop）はホストとして機能します。クライアントはサーバーを起動または接続し、「どのようなツールがありますか？」と問い合わせ、モデルがツールが有用だと判断したときにそれを呼び出します。サーバー内部からモデルを呼び出すことはありません。フローは逆方向に動きます。
この方向性が重要です。あなたのサーバーは受動的なプロバイダーです。クライアントの接続を待ち、発見リクエストに応答し、呼び出されたツールを実行します。このメンタルモデルを持てば、このチュートリアルの残りの部分がすんなりと理解できるはずです。
PythonでMCPサーバーを構築する方法（ステップバイステップ）
Pythonは、FastMCPがプロトコルの基盤処理を行い、デコレータを使ってplainな関数をツールに変換してくれるため、稼働中のサーバーへの最短ルートです。以下のすべては公式Python SDKを使用しています。手順は4つです。
ステップ1：プロジェクトの設定。 現在MCP Pythonプロジェクトの標準となっているuvを使用します。
uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"pipを好む場合: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]"。
ステップ2：サーバーの記述。 server.pyを作成します。
from mcp.server.fastmcp import FastMCP
import httpx
# Name shows up in the client's tool list
mcp = FastMCP("demo-server")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers and return the sum."""
return a + b
@mcp.tool()
async def fetch_url(url: str) -> str:
"""Fetch a URL and return the first 2000 characters of the body."""
async with httpx.AsyncClient(timeout=10) as client:
resp = await client.get(url)
return resp.text[:2000]
if __name__ == "__main__":
mcp.run() # defaults to stdio transport注目すべき点が2つあります。docstringはモデルが読むツールの説明になるため、指示のように記述してください。また、型ヒント（a: int）は自動的に入力スキーマになるため、FastMCPがJSON Schemaを生成してくれます。
ステップ3：実行。 mcp.run()はstdio上でサーバーを起動します。これはクライアントがローカルで起動するトランスポートです。開発中はこれを直接実行しません。クライアントが起動します。簡単なスモークテストには、devランナーを使用します。
uv run mcp dev server.pyステップ4：クリーンな出力を返す。 ここで注意すべき落とし穴：レンダリングされることを期待して生のネストされたdictを返すのではなく、文字列または型付きの値を返してください。本番セクションで理由に戻りますが、要約すると、曖昧な戻り値の型は一部のクライアントでサイレントに切り捨てられる可能性があります。
これで完全なPython MCPサーバーの完成です。2つのツール、実際のネットワーク呼び出し、自動スキーマ生成。次に、TypeScriptで同じことを行います。
TypeScriptでMCPサーバーを構築する方法（ステップバイステップ）
TypeScriptパスは、公式TypeScript SDKを直接使用し、入力検証にzodを使用します。FastMCPよりも少し冗長ですが、型付けが優れており、Nodeホストへのデプロイがクリーンです。
ステップ1：プロジェクトの設定。
mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsxステップ2：サーバーの記述。 server.tsを作成します。
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({ name: "demo-server", version: "1.0.0" });
server.tool(
"add",
"Add two numbers and return the sum.",
{ a: z.number(), b: z.number() },
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
}),
);
server.tool(
"fetch_url",
"Fetch a URL and return the first 2000 characters.",
{ url: z.string().url() },
async ({ url }) => {
const resp = await fetch(url);
const body = await resp.text();
return { content: [{ type: "text", text: body.slice(0, 2000) }] };
},
);
const transport = new StdioServerTransport();
await server.connect(transport);ステップ3：実行。 開発中は: npx tsx server.ts。本番環境では、tscでコンパイルし、ビルドされた.jsをNodeで実行します。戻り値の形状に注目してください。すべてのツールは{ content: [{ type: "text", text: ... }] }を返します。この明示的なcontent配列は、Pythonの「クリーンな文字列を返す」ルールに対するTypeScript相当物です。SDKは生オブジェクトではなく、型付けされたコンテンツブロックを必要とします。
ステップ4：zodで入力を検証。 z.string().url()スキーマは、ハンドラーが実行される前に不正な入力を拒否するため、モデルが引数を生成している場合にまさに望ましい動作です。
同じ2つのツール、同じ動作、慣用的なTypeScript。次に、クライアントがサーバーにどのようにアクセスするかを決めましょう。
stdio対Streamable HTTP：どのトランスポートを使用すべきか？
MCPサーバーは2つのトランスポートのいずれかで通信します。stdioは、クライアントが起動し、標準入出力を通じて通信するローカルサブプロセスとしてサーバーを実行します。Streamable HTTPは、クライアントがHTTP経由で接続するネットワークサービスとしてサーバーを実行します。サーバーが存在すべき場所に基づいて選択してください。
| stdio | Streamable HTTP | |
|---|---|---|
| 実行場所 | ローカル、クライアントによって起動 | リモートまたはローカル、Webサービスとして |
| 適している用途 | 個人用ツール、開発、単一マシン | 共有サーバー、チーム、SaaS、クラウド |
| 認証 | ユーザーのマシンを継承 | OAuth 2.1 / トークン認証が必要 |
| 設定コスト | 最低（コマンドのみ） | ホスティング + エンドポイントが必要 |
| 測定されたオーバーヘッド | 呼び出しあたり約8-12 ms（ローカル） | 呼び出しあたり約40-70 ms（ネットワーク依存） |
経験則：stdioで構築およびテストし、複数の人或いはマシンがサーバーを必要とする場合にのみStreamable HTTPに切り替えてください。ほとんどのサーバーはstdioを出る必要がありません。上記のmcp.run()およびStdioServerTransport()呼び出しはすでにstdioであるため、開発用の準備は完了です。
InspectorでMCPサーバーをテストする方法
サーバーをClaudeに接続する前に、MCP Inspectorを使用して孤立した状態でテストしてください。これはブラウザUIで、サーバーに接続し、ツールを一覧表示し、手動で呼び出すことができます。サーバーに対して実行します。
# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.tsInspectorはローカルページを開き、addおよびfetch_urlツールを表示し、テスト呼び出しを発行し、生の応答を読み取ることができます。これはMCP開発における最も優れた習慣です。ツールのスキーマが不正だったり戻り値が間違っていた場合、Claude内の沈黙した失敗を見つめるのではなく、ここで数秒以内に発見できます。私たちはこの方法で、 otherwise クライアントを通じた完全なデバッグ往復を要していたであろう不正な入力スキーマを発見しました。毎回まずInspectorでテストしてください。
MCPサーバーをClaude Desktop、Claude Code、Cursorに接続する方法
Inspectorで問題なければ、実際のクライアントをサーバーに向けます。各クライアントは、stdio経由でサーバーを起動する方法を指示する設定ファイルを読み取ります。
Claude Desktop。 claude_desktop_config.jsonを編集します（macOSの場合: ~/Library/Application Support/Claude/claude_desktop_config.json）：
{
"mcpServers": {
"demo-server": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
}
}
}Claude Desktopを再起動すると、ツールがコネクタアイコンの下に表示されます。
Claude Code。 プロジェクトから1つのコマンドでサーバーを追加します: claude mcp add demo-server -- uv run server.py。Claude Codeはこれをプロジェクト設定に保存し、起動時に読み込みます。フックを使用してClaude Codeをスクリプト化する場合、カスタムMCPツールとうまく組み合わせられるClaude Codeフックガイドも参照してください。
Cursor。 プロジェクトルートの.cursor/mcp.jsonに同じmcpServersブロックを追加します。形状はClaude Desktopのものと同じです。Claude Code内で実行されているMCPサーバーの実例については、HiggsfieldをClaude Codeに接続した方法をご覧ください。
すべての設定で絶対パスを使用してください。相対パスは、サーバーの起動失敗の最も一般的な原因です。
本番環境へのMCPサーバーデプロイ（認証とホスティング）
サーバーを共有する必要がある場合、stdioからStreamable HTTPに移行し、3つの要素を追加します。認証、エラー処理、ホストです。
- 認証。 リモートMCPサーバーは、MCP認証仕様に従いOAuth 2.1を使用する必要があります。社内ツールの場合、HTTPエンドポイントでのBearerトークンチェックが実用的な最小限です。SQLを実行したり内部APIにヒットしたりするツールは生きた攻撃対象となるため、公開された未認証のツールサーバーを決して出荷しないでください。
- エラー処理。 ツール本体をtry/except（またはtry/catch）で囲み、投げる代わりに型付きのエラーメッセージを返します。モデルは「クエリが失敗しました。理由はこれです」という処理の方が、切断された接続よりもはるかにうまく扱います。
- ホスティング。 長寿命のNodeまたはPythonプロセスを実行できるプラットフォームならどれでも機能します。小型のVPS、Fly.io、Railway、または独自のインフラ上のコンテナなど。コールドスタートが最初のツール呼び出しにレイテンシーを追加するため、プロセスをウォーム状態に保ってください。
- 同時実行性とコスト。 ツールが下流でLLMまたは有料APIを呼び出す場合、その前にゲートウェイを配置してください。LLMゲートウェイツールのまとめはレート制限とフォールバックをカバーしており、コンテキストエンジニアリングツールはツール出力がモデルのコンテキストウィンドウを膨張させるのを防ぎます。
Pythonの場合、実行呼び出しをmcp.run(transport="streamable-http")に変更します。TypeScriptの場合、StdioServerTransportをSDKのStreamableHTTPServerTransportに置き換えます。ツールの定義はまったく変更されません。これがトランスポート抽象化のポイントです。
本番環境でMCPサーバーを出荷して学んだこと
Techsyでは社内利用のためにMCPサーバーを構築してきましたが、いくつかの教訓は実際のトラフィックが発生して初めて明らかになります。私たちが測定したことと、痛手を受けた箇所はこちらです。
最初に出荷したサーバーは、Python mcp 1.x SDK上のFastMCP 2.xで構築された読み取り専用のPostgresクエリツールで、後に比較のために@modelcontextprotocol/sdk 1.xで書き直されました。2026年のスタック（Node 20、Python 3.11）では、ローカルのstdioツール呼び出しは呼び出しあたり約8〜12 msのトランスポートオーバーヘッドを追加しました。同じサーバーをVPS上のStreamable HTTPに移行すると、呼び出しあたりのコストは40〜70 msに上昇し、ほぼすべてがプロトコルコストではなくネットワーク往復時間でした。FastMCPのコールドスタートはプロセスで約300 msだったため、本番プロセスはウォーム状態に保っています。
約2時間のコストとなった落とし穴：生のPython dictを返すツールはInspectorでは正常にレンダリングされましたが、Claude Desktop内では切り捨てられて返ってきました。戻り値を型付きテキスト文字列としてラップすることで即座に修正されました。そのため、このチュートリアルではネストされたオブジェクトではなく、あらゆる場所で文字列とcontentテキストブロックを返しています。もう一つすぐに報われた習慣は、クライアント設定に触れる前にnpx @modelcontextprotocol/inspectorを通じてすべてのサーバーを実行することでした。これにより、TypeScript書き直し時の不正な入力スキーマが発見され、否则Cursorでサイレントに失敗していたでしょう。
| 使用したもの | バージョン |
|---|---|
Python mcp SDK | 1.x |
| FastMCP | 2.x |
@modelcontextprotocol/sdk (TS) | 1.x |
| Node.js | 20 LTS |
| Inspector | @modelcontextprotocol/inspector (latest) |
最初にサーバーにどのツールを構築するか選んでいる場合、2026年のベストMCPサーバーのリストは良いアイデアバンクとなります。
TechsyのMCP開発アプローチ
Techsyでは、MCPサーバーをクライアント向けに出荷するAIエージェントシステムの一部として構築し、型付けされたツール層を通じてエージェントを内部データベース、CRM、APIに接続しています。私たちのアプローチは、狭く始めること（stdio上の十分にテストされた1つのツール）、Inspectorで検証すること、そして複数のエージェントが必要になった場合にのみ認証済みHTTPサービスに昇格させることです。エージェントロジックが複雑になる場合は、カスタムサーバーをClaude Agent SDKと組み合わせて使用します。
正直な話：ほとんどのチームは最初のサーバーを作りすぎています。初日からHTTP、OAuth、そして十数のツールが必要になることはめったにありません。MCP統合についてセカンドオピニオンが必要な場合は、無料相談にご連絡ください。それが1つのツールのstdio案件なのか、本当にインフラを必要とするものなのかをお伝えします。
よくある質問
MCPサーバーはPythonとTypeScriptのどちらで構築すべきですか？
チームがすでに出荷している方を使用してください。FastMCPを使用したPythonは、デコレータが関数をツールに変換するため、最初の稼働サーバーへの最短ルートです。公式SDKを使用したTypeScriptは少し冗長ですが、優れた型付けを提供し、Nodeホストにクリーンにデプロイできます。どちらもクライアントに対して同一の動作をするサーバーを作成します。
MCPサーバーを構築するためにFastMCPのようなフレームワークが必要ですか？
いいえ、ただし役立ちます。FastMCPは公式Python mcp SDK内に同梱されており、プロトコルのボイラープレートの大部分を取り除きます。細かな制御のために低レベルのServer APIを使用することもできますが、ほぼすべてのサーバーにおいて、FastMCP（Python）またはMcpServer（TypeScript）が適切なツールであり、コード量がはるかに少なくなります。
動作しないMCPサーバーをデバッグするにはどうすればよいですか？
まずMCP Inspectorを通じて実行します: npx @modelcontextprotocol/inspectorの後に実行コマンド続けます。Inspectorはツールを一覧表示し、直接呼び出すことができるため、クライアントを責める前にサーバーが動作することを確認できます。Inspectorは正常だがクライアントが正常でない場合、設定で絶対パスを使用しているか、クライアントを再起動したかを確認してください。
FastMCPはMCPの公式部分ですか？
はい。FastMCPは、ハイレベルなサーバーインターフェースとして公式Model Context Protocol Python SDKにバンドルされています。使用する@mcp.tool()デコレータは、サードパーティのアドオンではなく、Pythonサーバーを構築するための推奨される方法です。
ローカルMCPサーバーとリモートMCPサーバーの違いは何ですか？
ローカルサーバーはマシン上でstdio経由で実行され、クライアントによってサブプロセスとして起動されるため、個人用ツールと開発に最適です。リモートサーバーはStreamable HTTP経由でWebサービスとして実行され、複数のクライアントから到達可能であり、OAuth 2.1認証が必要です。まずはローカルで構築し、共有する場合のみリモートに移行してください。
どの言語でMCPサーバーを構築できますか？
Model Context Protocolには、Python、TypeScript、Java、Kotlin、C#用の公式SDKがあり、他の言語にはコミュニティSDKがあります。MCPはワイヤープロトコルであるため、stdioまたはHTTP経由でJSON-RPCを読み書きできる任意の言語でサーバーを実装できますが、公式SDKはその作業を節約してくれます。
MCPサーバーはChatGPTやGeminiでも動作しますか、それともClaudeのみですか？
MCPは、ChatGPT、Gemini、Cursor、VS Code Copilotを含むエージェンティックAIエコシステム全体で採用されているオープンスタンダードです。構築した単一のサーバーは、互換性のあるあらゆるクライアントで動作します。モデルごとに別々の統合を書く必要はありません。それがプロトコルの存在意義です。
動作するMCPサーバーの構築にはどのくらい時間がかかりますか？
ランタイムがインストールされていれば、stdio上で動作する1つまたは2つのツールを持つ最初のサーバーは約15分で完成します。Node 20での初心者向けに14分、再構築では5分未満を計測しました。認証、HTTPトランスポート、本番ホスティングの追加に実際の時間がかかるのであり、サーバー自体ではありません。
著者について
Mert Batur GurbuzはTechsy.ioの共同創業者であり、同チームはB2Bクライアント向けにAIエージェント、自動化システム、音声/SDRパイプラインを出荷しています。バーミンガム大学で学び、Techsyチームが生産環境で実際に使用しているLLMツールスタックについて執筆しています。LinkedInでつながってください。
Mert Batur Gurbuz, 共同創業者, Techsy.io, バーミンガム大学