MCPサーバー構築手順｜stdio最小実装から接続確認まで

MCPを触り始めたとき、私はまず stdio の最小実装をClaude for Desktopに追加しました。
ところが設定を書き換えただけで安心しているとサーバーが見つからず、原因はアプリの完全再起動を忘れていたことでした。
この記事は、その最初のつまずきを避けつつ、ローカルで最小のMCPサーバーを作り、Claude for DesktopVS CodeCursorから認識・実行できるところまでを30〜60分でたどる内容です。

PythonかTypeScriptのどちらかが使えるなら再現できる構成に絞るので、MCPの全体像をつかみたい初心者にも、既存のAPI連携をMCP化したい中級者にもそのまま手を動かせるはずです。
遠回りになりがちな本番向けの話は後段に回し、最初は「ローカルで確実に動く一台」を作るところから始めます。

MCPサーバーとは何か｜自作する前に押さえる全体像

MCPはModel Context Protocolの略で、AIモデルと外部のツールやデータソースをつなぐためのオープン標準です。
ここでいう「標準」は、特定のアプリ専用の独自連携ではなく、ルールに沿って作れば複数のホストから同じ考え方で接続できる、という意味です。
実装例としてはClaude for DesktopやVS Code、OpenAI Apps SDKまわりでの採用事例が報告されていますが、各実装が公式にどのトランスポートを逐語で列挙しているかは差があります。
具体的な対応トランスポートや設定手順は、各プロダクトの公式ドキュメント（例: Model Context Protocol 公式ドキュメント）を併せて確認してください。

MCPサーバーが提供する3つの機能

MCPサーバーが公開する機能は、基本的に Tools Resources Prompts の3種類です。
『Build an MCP server』でもこの前提で説明されています。

Tools は、AIが外部で何かを実行するための道具です。
たとえば「GitHubのIssueを作成する」「Slackにメッセージを送る」「天気APIを呼ぶ」といった、引数を渡して処理を走らせるものがここに入ります。
関数呼び出しに近いイメージです。

Resources は、AIが参照するためのデータです。
たとえばローカルの設定ファイル、社内ドキュメント、特定リポジトリのREADME、Notionのページ内容などが当てはまります。
実行よりも「読む」「取り込む」に寄った役割だと考えると整理しやすくなります。

Prompts は、AIに渡す定型の指示テンプレートです。
たとえば「このリポジトリをレビューするための観点を含んだプロンプト」や「問い合わせ内容から障害報告テンプレートを生成するプロンプト」のように、毎回ゼロから書かずに済むひな型を提供します。

この3つを分けて考えると、「外部APIを叩くなら Tools」「資料を読ませるなら Resources」「毎回使う指示文を共通化するなら Prompts」という判断がつきます。
自作に入る前にこの分類が頭に入っていると、サーバー設計がぶれません。

Build an MCP server - Model Context Protocol

Get started building your own server to use in Claude for Desktop and other clients.

modelcontextprotocol.io

「中継役」ではなく「機能提供プログラム」と見る

MCPサーバーを単なる中継役として捉えると、実装の輪郭がぼやけます。
実際には、サーバーはホストから受けた要求に応じて、利用可能な Tools Resources Prompts を列挙したり、ツール実行を受け付けたり、必要なデータを返したりする機能提供側のプログラムです。
たとえばGitHub APIやSlack APIを裏で使うサーバーなら、外部サービスとの認証や権限管理、レスポンス整形の責任はサーバー側に置かれます。

この見方に切り替えると、「MCPサーバーを作る」とは、巨大な基盤を新設することではなく、AIに渡したい能力を小さく切り出して公開する作業だとわかります。
最初の一台として天気取得やローカルファイル参照のような小粒なテーマが向いているのは、そのためです。
1つのサーバーに役割を詰め込みすぎるより、目的ごとに分けたほうが構造も追いやすくなります。

構築前の前提条件｜必要な環境と最初の選択

ローカル優先で始める安全設計

最初の構築は、公開サーバーではなくローカルの stdio 構成から入るのが筋です。
理由は単純で、MCPサーバーはツール実行や外部データ参照の窓口になるぶん、権限の切り方を誤ると影響範囲が広がるからです。
公開状態のMCPサーバーは、認証や認可が弱いと機密データへの入口になり得ることがTrend Microや。
まずは手元のプロセスとして起動し、渡している環境変数、触れているファイル、呼び出せるツールの範囲を目で追える形にしておくと、どこまで許可したのかを把握したまま検証できます。

ローカル優先が向いているのは、通信そのものが短い経路で閉じるからでもあります。
stdio ならホスト側のクライアントがMCPサーバーのプロセスを直接起動し、標準入出力でやり取りします。
最小構成の確認という意味ではこれが最短です。
小さなサーバーを作って接続する流れが基本になっています。
しかも stdio では console.log() のようなstdout出力が通信を壊すため、ログの置き場所を最初に意識できます。
実際に触ってみると、この制約があるおかげで「通信に使う出力」と「デバッグ用ログ」を分けて考える癖が付きます。

もうひとつ、公式クイックスタートが weather server を題材にしているのも、ローカル開始と相性が良い判断材料になります。
天気情報そのものが目的ではなく、「引数を受け取るツールを1つ生やして、クライアントから呼べるところまで見る」ための最小例としてまとまっているわけです。
自作でも、まずは weather server と同じ粒度の小さなツールに寄せると進めやすくなります。
たとえば「文字列を受け取って整形して返す」「固定JSONを返す」くらいの単機能で十分です。
ここで1回成功しておくと、後から Resources や Prompts を足しても構造を見失いません。

PythonかTypeScriptかの初手判断

言語選びは、将来の理想像より「最初の30分で何を確認したいか」で決めるとぶれません。
試作をすばやく回したいならPython、Node系の開発基盤やエディタ連携を前提にするならTypeScript、という切り分けでほぼ整理できます。
MCPサーバーは最初の段階では小さな入出力の整形が中心なので、言語の優劣というより、手元の環境でどちらが止まらず進むかが判断軸になります。

筆者の最初の実感（Python）

筆者は最初に Python で試しました。パッケージ導入の手戻りが少なく、最小ツールの動作確認までの距離が短いと感じました。

TypeScript の接続上の利点

TypeScript は VS Code や Cursor といったエディタ中心のワークフローとの親和性が高く、型の恩恵でツール入出力スキーマを詰めやすい点が強みです。

判断に迷うなら、次のように考えると決めやすくなります。
Pythonは「まず動かす」ための初手に向き、TypeScriptは「エディタ連携やHTTP展開まで見据える」流れに乗せやすい、という違いです。
どちらも正解になり得ますが、最初のサーバーで目指すのは weather server 相当の最小例です。
そこで必要なのは高度な設計より、クライアントから1回呼び出せる状態です。

使うクライアントを1つに決める

MCPサーバーを初回でつまずかせないコツは、サーバーの実装と同じくらい「接続先を増やしすぎない」ことです。
Claude for DesktopVS CodeのGitHub Copilot連携、Cursor、OpenAI Apps SDK系の接続先はどれも魅力がありますが、最初は1つに絞ったほうが原因の切り分けが早くなります。
サーバー実装、起動方法、クライアント設定の3点が同時に動く必要があるので、接続先まで複数にすると、どこで失敗したのか見えにくくなります。

初手としてわかりやすいのはClaude for Desktopです。
ローカルMCPサーバーを設定ファイルに追加して再起動し、ツール一覧に出るかを見る流れが比較的追いやすいからです。
手元で stdio の最小実装を確かめるなら、この経路は今でも有力です。
前述の通り、設定変更後はアプリを完全終了してから立ち上げ直す必要があり、ここを飛ばすと「実装は正しいのに表示されない」という状態に入りがちです。

Cursorはエディタ一体型の体験を作りやすく、MCPサーバーの追加（UIや設定ファイル経由）や接続状態のインジケータを持つ運用が知られています。
ただし、Cursor が公式にどのトランスポートを逐語でサポートしているかはドキュメント差があるため、トランスポートの詳細は公式の導入ガイドを確認することを推奨します。
実際に進めると、1つのクライアントで成功体験を作ったあとに2つ目へ横展開するほうが速いです。
最初からClaude for DesktopとVS CodeとCursorを同時に合わせるより、「このサーバーはクライアントAでは見えている」という足場を作ったほうが、設定ミスか実装ミスかを切り分けられます。

設定ファイルとUIの更新に注意

MCPまわりで時間を取られやすいのは、コードより設定反映です。
サーバー本体は正しくても、クライアント側の設定場所や再読み込み方法が合っていないと認識されません。
VS Codeでは .vscode/mcp.json をワークスペース設定として置く方法と、ユーザー設定として管理する方法が分かれています。
前者はプロジェクトごとに閉じた設定、後者は手元の全体設定という違いがあり、どちらを触っているのか曖昧なまま進めると、保存したのに反映されない原因になります。
チームで共有するなら .vscode/mcp.json をリポジトリに含められる点も把握しておくと流れがきれいです。

Claude for Desktopは claude_desktop_config.json の編集後に完全終了と再起動が必要です。
ここはUIの再表示だけでは足りません。
筆者もこの点で一度止まりましたが、設定変更を細かく繰り返す場面では、アプリ側に反映させる前にMCP Inspectorで先に疎通を見るほうが効率が上がります。
アプリ再起動の手間を減らせるからです。

UIや設定パスは更新で動くことがありますが、ここで気にしたいのは曖昧な一般論ではなく、今使っているクライアントでどのファイルが読み込まれるかです。
VS Codeなら mcp.json の置き場所、Claude for Desktopなら設定ファイル編集後の完全再起動、CursorならMCP追加画面や設定ファイルのどちらで登録したか、この3点を揃えるだけで初回の詰まりどころはだいぶ減ります。
初手では最小のweather server相当を1本、クライアントも1つ、設定反映の確認ポイントも1つに絞る構成が、結果としていちばん短く動作確認まで届きます。

最小のMCPサーバーを作る手順｜stdioでまず動かす

Pythonで最小のTools実装

最初の1本は、公式のBuild an MCP serverに沿って、Toolsだけを公開する最小構成に寄せるのが素直です。
MCPのサーバーはToolsResourcesPromptsを持てますが、初回はツール呼び出しに絞ったほうが成功判定が明確です。
クライアントからツール一覧に見えるか、1回呼べるか、結果が返るか。
この3点だけ見ればよく、Resources や Prompts まで同時に広げるより切り分けが短く済みます。

Pythonなら、引数を受けて文字列を返すだけのツールを1つ置けば十分です。
たとえば echo_tool のような名前で、入力した文字列をそのまま返す実装なら、通信・登録・呼び出しの成否を追いやすくなります。
処理内容に業務ロジックを入れないこともポイントで、最初は「MCPとして呼べた」ことだけを確認対象にします。

from mcp.server.fastmcp import FastMCP
import sys

## mcp = FastMCP("minimal-tools")

### @mcp.tool()
def echo_tool(text: str) -> str:

from mcp.server.fastmcp import FastMCP import sys

mcp = FastMCP("minimal-tools")

@mcp.tool()

def echo_tool(text: str) -> str: return f"echo: {text}"

if __name__ == "__main__": print("starting minimal-tools", file=sys.stderr) mcp.run()

> [!WARNING]
> 上の Python サンプルは概念的な例示です。`FastMCP` やデコレータ名、初期化の方法などは SDK やバージョンによって異なる可能性があります。実装時は使用する SDK の公式リファレンス（お使いのバージョン）を必ず参照してください。

この段階で見ているのは、ツールの価値ではなく**プロトコルの通り道が通っているか**です。Python系の試作はこの形にすると迷いが減ります。`FastMCP` の名前、ツール名、引数1つ、戻り値1つだけにしておくと、エラーが出たときも原因候補が広がりません。
Node.jsやVS Codeまわりに慣れているなら、TypeScriptでも同じ考え方で始められます。ここでも狙いは最小のTools実装です。ツールが1つだけなら、クライアント登録後に「見えるか」「呼べるか」をそのまま確認できます。

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod";

const server = new McpServer({ name: "minimal-tools", version: "1.0.0",

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

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

server.tool(
  "echo_tool",
  { text: z.string() },
  async ({ text }) => {
    return {
      content: [{ type: "text", text: `echo: ${text}` }],
    };
  }
);

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

TypeScript版でも、最初は非同期処理や外部API連携を入れない構成のほうが追跡しやすくなります。
zod で引数を定義し、固定フォーマットで返すだけにしておくと、引数バリデーションとレスポンス形式の両方を一度に確認できます。
TypeScript SDKはその後のStreamable HTTP展開にもつなげやすいですが、出発点としては stdio のほうが部品数が少なく、ローカル検証の最短距離になりやすいのが利点です。

stdio 構成では、正常系の通信もエラー時の手がかりも混線しやすいので、stdoutはMCP専用、ログはstderr専用と最初に決めておくと、接続不良の切り分けが進みます。

サーバー起動と確認

stdio サーバーの起動コマンドは、クライアントがそのままプロセス起動できる形で考えると整理しやすくなります。
要点は3つで、実行ファイルの場所が通っていること、必要な環境変数が揃っていること、実行権限があることです。
ここが曖昧なままコードだけ直しても、接続は安定しません。

Pythonなら python /絶対パス/server.py のように、まずは絶対パスで起動する前提に寄せるとぶれません。
仮想環境を使うなら、そのPython実体を指す書き方にします。
TypeScriptは node dist/server.js のようにビルド後ファイルを起動する形が扱いやすく、開発中に ts-node や tsx を噛ませる場合も、クライアント設定に書くコマンドをそのままターミナルで再現できる形にしておくと切り分けが短くなります。

macOSやLinuxではシェル経由の起動が通る一方で、Windowsではパスの空白や実行ファイルの場所で詰まりやすい場面があります。
python や node がPATHにないなら、実行ファイルのフルパスを書いたほうが確実です。
環境変数を使う場合も、クライアントから起動されるプロセスにその値が渡る前提で設定します。
端末では動くのにクライアントからは失敗するケースは、この差で起きることが多いです。

起動確認は、先にクライアントへ登録する前に、コマンド単体で破綻しないかを見ます。
そのうえでMCP Inspectorを使うと、ローカルの stdio サーバーがツール一覧を返せるかを先に見られます。
デスクトップアプリを何度も閉じたり開いたりするより、Inspectorで1回つないでからクライアント登録へ進めたほうが手戻りが減ります。

MCP Inspector - Model Context Protocol

In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers

modelcontextprotocol.io

クライアント登録と“完全再起動”のコツ

クライアント登録では、Claude for DesktopかVS Codeのどちらか1つに絞るのが無難です。
Claude for Desktopなら claude_desktop_config.json の mcpServers にサーバー定義を追加します。
データシートで確認できている通り、設定ファイルの場所はWindowsでは %APPDATA%\Claude\claude_desktop_config.json、macOSでは ~/Library/Application Support/Claude/claude_desktop_config.json です。
ここにコマンド、引数、必要なら環境変数を記述して、アプリを終了してから起動し直します。

VS Code系で進めるなら、公式のVS CodeでMCPサーバーを追加・管理する方法にある mcp.json ベースの登録が基準になります。
ワークスペース単位の .vscode/mcp.json か、ユーザー単位の設定かを最初に固定しておくと、どちらを見ているのか混乱しません。
特にGitHub Copilot連携では、設定を書いた場所と実際に読まれる場所がずれると、サーバーが存在しないように見えます。

ここで効くのが“再読み込み”ではなく完全再起動です。
Claude for Desktopは設定変更後に完全終了してから起動し直す手順が複数の案内で示されていて、ウィンドウを閉じただけでは反映されないことがあります。
筆者も最初、設定ファイルを書き換えて画面を見直しただけで安心して止まりましたが、プロセスを落として立ち上げ直すとツールが出ました。
小さな修正を何度も試す場面では、この待ち時間が積み上がるので、サーバー本体の疎通確認は先にMCP Inspectorで済ませ、クライアント側にはまとまった変更を入れる流れのほうが無駄が少なくなります。

登録後に見るポイントも、最初は絞ったほうがよいです。
ツール一覧に echo_tool が見えること、1回呼んで文字列が返ること、この2点だけで十分です。
ここで応答が見えない場合、コードを疑う前に起動コマンド、設定ファイルの場所、完全再起動、そしてstdout汚染の4点を見直すと、初回の失敗原因はだいたい絞れます。

Add and manage MCP servers in VS Code

Learn how to add and manage Model Context Protocol (MCP) servers with GitHub Copilot in Visual Studio Code.

code.visualstudio.com

クライアントに接続して動作確認する

Claude for Desktopでの認識チェック

Claude for Desktopは、設定を書いただけでは反映されたか判断しにくい場面があります。
そこで見る場所を最初から固定しておくと、サーバー実装の問題なのか、クライアント側の読込なのかを分けて追えます。
実際には、claude_desktop_config.json に追記したサーバー定義が読み込まれていれば、入力欄まわりのツール表示に変化が出て、呼び出し候補の中に登録したサーバー由来のツールが現れます。
前のセクションで触れた echo_tool のような最小ツールなら、名前が一覧に出るか、実行ダイアログに候補として出るか、この2点で認識確認が進みます。

ここで反映されないとき、コードを先に疑うより、設定ファイルの場所とJSONの構文、起動コマンドの絶対パス指定を見直したほうが早く詰められます。
私も最初は設定を書き換えて画面だけ見直して空振りし、その後に再起動してツール一覧に出たことがありました。
Claude for Desktopは“読めていない”状態と“サーバーは起動したがツール公開に失敗している”状態がUI上で似て見えるので、表示有無の確認だけでも手順を固定しておく価値があります。

VS Code/Copilotのmcp.json管理

VS CodeとGitHub Copilot系では、.vscode/mcp.json をワークスペースに置く運用と、ユーザー単位で持つ運用が混在すると、同じリポジトリを開いていても人によって見えているサーバー定義がずれます。
mcp.json ベースの管理が前提になっていて、どこに定義を書くかが最初の分岐になります。

共同開発では、私は .vscode/mcp.json をそのままソース管理に入れるやり方に落ち着きました。
これをやると、少なくとも起動コマンドや引数の書き方はチームで揃います。
ローカルの秘密情報まではコミットせず、環境変数参照だけ残す形にしておけば、手元ごとの差分は最小限で済みます。
新しく参加したメンバーがサーバー名のタイプミスや引数不足で詰まる場面も減るので、チーム開発では効きます。

個人用のユーザー設定に切り替えると、複数のリポジトリで同じMCPサーバーを使うときに管理が楽になります。
反対に、リポジトリ単位で共有したい場合は .vscode/mcp.json をワークスペースに置く運用が向いています。

Cursorでの有効化確認の観点

Cursorの公式ドキュメントで基本的な導入手順は確認できますが、トランスポートの逐語的な完全一覧や内部ログの保存場所などは明確でない場合があります。
そのため、実務ではUIの表示とサーバーログを突き合わせて確認する運用が現実的です。

ここで意識したいのは、Cursorは更新頻度が高く、MCP関連のメニュー名や配置が変わることがある点です。
画面上のラベルを丸暗記するより、MCPサーバー一覧、接続状態インジケータ、ツール候補表示という3つの観点で覚えたほうが、UIが動いても追従できます。
メニュー名が少し変わっても、見るべきもの自体は大きく変わりません。

MCP Inspectorでの通信確認

クライアントに登録してから挙動を見る方法でも進められますが、通信そのものを見たいならMCP Inspectorを挟むと一気に輪郭が出ます。
Model Context Protocol公式のMCP Inspectorは、MCPサーバーのテストとデバッグ向けに作られていて、stdio、SSE、Streamable HTTP を扱えます。
メッセージの流れ、公開されたツール、呼び出し結果を可視化できるので、「クライアントで見えない」の原因がサーバー側かクライアント側かを分けるのに向いています。

手元では、クライアントを何度も開き直す前にInspectorで tools/list 相当のやり取りが成立するかを見ることが増えました。
ここでツールが見えて呼び出しも通るなら、サーバー実装はひとまず通っていると判断できます。
逆にInspectorでも失敗するなら、クライアント固有の問題ではなく、起動コマンド、引数、環境変数、トランスポート実装のどこかに絞れます。

また、Streamable HTTP に進んだ段階では、HTTPで届いているのにMCPセッションが維持できていないケースも出ます。
トランスポートごとに見える失敗の形が違うので、HTTPの疎通確認だけで安心しないほうが流れを読み違えません。
stdio ではプロセス起動と標準入出力、HTTPではエンドポイントやセッション管理と、観察点が入れ替わります。

失敗時の切り分けフロー

接続できないときは、原因候補を一列に並べて上から潰すと混乱しません。
私が実際によく使う順番は、サーバープロセスの生存、stdout 汚染、クライアント設定、権限や認可、トランスポート不一致の5段です。
この順に見ると、手前の単純な問題を飛ばして深い層に潜る事故を避けられます。

まず見るのは、クライアントからサーバープロセスが起動しているかです。
プロセスが立ち上がっていなければ、MCP以前にコマンド解決、パス、実行権限、必要ファイルの欠落が候補になります。
起動してすぐ落ちるなら、依存パッケージ不足や環境変数不足が濃くなります。
端末では動くのにクライアントでは失敗するなら、クライアントが引き継いでいる環境が違うと考えると筋が通ります。

次に確認すべきは stdout の汚染です。
stdio では標準出力が通信路になるため、デバッグ出力が混ざると通信が壊れます。
ログは stderr に逃がして再試行してください。

その次がクライアント設定です。
Claude for Desktopなら claude_desktop_config.json のJSON崩れやサーバー名の記述ミス、VS CodeやCopilotなら .vscode/mcp.json とユーザー設定のどちらを読んでいるかの取り違えが典型です。
Cursorでも、見えている設定ファイルと実際に有効な定義が別だった、という形で同じ問題が出ます。
設定ファイルの場所と、そこに書いた起動コマンドをターミナルでそのまま再現できるかを揃えると、誤差が減ります。

権限や認可も、接続後に止まる原因として見逃せません。
Copilot系では組織ポリシーがMCP利用を止めていることがありますし、OAuth連携型のサーバーでは、サーバー自体は見えていてもトークン不足で実ツールだけ失敗することがあります。
この段階では「サーバーが見えない」のではなく「見えているが使えない」ので、症状の切り分けを分けて記録すると追いやすくなります。

トランスポート不一致は、深い層のわりに破壊力があります。
サーバーが stdio 前提なのにHTTP接続を試していたり、Streamable HTTP 実装なのに古いSSE前提の設定でつないでいたりすると、疎通しない理由が見えにくくなります。
MCPでは stdio がローカル開発の起点として扱いやすく、Streamable HTTP はその次の段階で理解すると流れが崩れません。
通信できないときほど、サーバー実装のトランスポートとクライアント設定のトランスポート名を言葉のレベルで一致させると、遠回りが減ります。

Streamable HTTP入門｜stdioとの違いと使い分け

仕様の変更点と現在地

MCPの標準トランスポートはstdio と Streamable HTTP の2種類です。
ここを先に固定しておくと、実装記事やサンプルを読むときに旧情報へ引っ張られにくくなります。
2025-03-26版で従来のHTTP+SSE前提の整理が進みました。
現在はStreamable HTTPが標準のHTTP系トランスポートとして置き換える形で扱われています。
旧HTTP+SSEは後方互換の文脈では知っておく価値がありますが、新規実装の起点としては中心から外れました。

この変更の実務上の意味は、HTTP接続の設計が分離された複数経路から、1つのエンドポイントに寄せやすくなったことです。
以前の方式は、HTTP POSTとSSEの受け口を分けて考える必要があり、MCPそのものの理解とは別に通信経路の整理で手が止まりやすいところがありました。
Streamable HTTPではその負担が軽くなり、プロキシ、認証、ログ収集、ルーティングの設計をHTTPの一般的な発想に寄せられます。
サーバーを社内ネットワーク越しに置く、本番で複数のホストアプリから呼ぶ、という絵が描きやすくなるのはこの点です。

手元でも、最初は stdio で最小構成を動かし、動作が固まってからHTTP化しました。
実際にHTTP化してみると、複数クライアントからの同時接続やリモート運用の見通しが一気に立ちました。
逆にローカルの初学習では stdio の速さが活きます。
プロセスを起動してそのまま標準入出力でつなぐだけなので、MCPの本体である tools/list や tools/call の感覚を先に掴めます。
Transport選定は優劣ではなく、学習段階では stdio、運用段階ではStreamable HTTPという順番で捉えると噛み合います。

実装面では、TypeScript SDKがv1.10.0からStreamable HTTP transportをサポートしたことで、Node系のMCPサーバーでも第一歩を踏み出しやすくなりました。
HTTP系の実装例が見られるように、MCPの接続先はローカルデスクトップだけでなく、Webアプリやリモート環境へ広がっています。
つまり、今の現在地は「まず stdio で学び、次にStreamable HTTPで運用へ寄せる」という流れが自然な段階です。

Build your MCP server

Wire tools, templates, and the widget runtime that powers ChatGPT Apps.

developers.openai.com

セッション管理とMcp-Session-Idの要点

Streamable HTTPに進むと、stdio にはなかった論点としてセッション管理が前面に出ます。
そこで押さえるべきなのが Mcp-Session-Id です。
基本の流れはシンプルで、サーバーがレスポンスでセッションIDを返し、クライアントは後続リクエストでその Mcp-Session-Id を継続して送ります。
HTTPとしては毎回別リクエストでも、MCPの会話としては同じ流れに束ねる、という役目です。

ここを曖昧にすると、「HTTP通信は通っているのに、前の文脈を引き継いでいない」「初回だけ成功して次で崩れる」という挙動になります。
前のセクションで触れた通り、HTTPでは疎通確認だけで安心できません。
ステータスコードが返ってきても、Mcp-Session-Id の受け渡しが切れていれば、MCPとしては連続した対話になっていないからです。
stdio ではプロセス自体が文脈の器になりやすい一方、HTTPではその役をヘッダーとサーバー側の管理が担います。

1エンドポイント化の利点も、このセッション管理と相性がいいところにあります。
入口が1つだと、認証ミドルウェア、リバースプロキシ、アクセスログ、監査の配置を一本化しやすく、MCP特有の処理をHTTP基盤の上に素直に載せられます。
旧HTTP+SSE方式では受信口と配信口が分かれるぶん、アプリケーションの責務とネットワークの責務が頭の中で分離しにくい場面がありました。
Streamable HTTPはその絡まりをほどいてくれます。

この違いは、本番運用を考え始めた瞬間に効いてきます。
たとえばCursorやGitHub Copilotのようにクライアントが増えると、1つのサーバーに対して複数セッションが並行して走る構図になります。
そのとき stdio の単純さは魅力ですが、単一プロセスに強く結び付いた運用から抜けにくい面があります。
Streamable HTTPなら、セッションごとの切り分け、HTTPレイヤーでの認証連携、ネットワーク越しの配置まで同じ延長線上で考えられます。

導入判断のフレーム

Transport選定で迷ったときは、まず「何を学びたい段階か」と「どこで動かしたいか」を分けて考えると筋道が立ちます。
ローカルで最初にMCPの基本動作を掴む段階なら stdio、複数クライアント接続やリモート配置を見据える段階ならStreamable HTTP、という整理です。
これは抽象論ではなく、実装コストの置き場が違うからです。
stdio はMCPの中身に集中でき、Streamable HTTPはMCPをネットワーク上で運ぶための設計まで含めて考えられます。

stdio を先に選ぶと、起動コマンド、標準入出力、ツール公開という最小単位に焦点を絞れます。
Claude for Desktopにローカルサーバーをつないで最初のツール呼び出しを通す段階では、この近さが効きます。
ログの見方も単純で、サーバープロセスの生死と stdout の汚染に集中できます。
学習初期にここを飛ばしてHTTPから入ると、MCPの理解とHTTP実装の理解が同時進行になり、どちらで詰まっているのか見失いがちです。

一方で、本番候補として考えるならStreamable HTTPに分があります。
HTTPベースなので、既存のWebインフラへ載せやすく、認証、TLS終端、プロキシ、監査ログ、複数クライアント接続といった運用要素を足していけます。
公開や社内提供を視野に入れると、MCPサーバーは単なるローカル補助ツールではなく、外部から到達可能なアプリケーションになります。
Trend Microの公開記事でも、ネットワーク越しに公開されたMCPサーバーが新しい攻撃面になり得る点が扱われています。
本番候補としてHTTPを選ぶなら、便利さと同時に防御設計までセットで考える必要があります。

導入判断をさらに具体化すると、次の3点で見ればぶれません。
ひとつ目は接続相手がローカルの1クライアントか、複数クライアントかです。
ふたつ目は同じマシン内で閉じるか、ネットワーク越しに運ぶかです。
みっつ目はMCP本体の学習が目的か、運用設計まで含めて固める段階かです。
この3つが前者に寄るなら stdio、後者に寄るならStreamable HTTPです。

実際の進め方としては、stdio で最小のサーバーを完成させ、tools/list と tools/call が安定してからHTTPへ持ち上げる流れが無理なくつながります。
TypeScriptならv1.10.0以降のTypeScript SDKでStreamable HTTP transportを使えるため、Node系の既存実装を横展開しやすくなりました。
学習の入口としての stdio と、本番候補としてのStreamable HTTP。
この二段階で考えると、Transport選定は悩みどころではなく、サーバーの成長段階を映す設計判断として見えてきます。

実装言語の選び方｜PythonとTypeScriptの向き不向き

Pythonに向く場面

Python SDKとTypeScript SDKはどちらも実装例が広く参照されていて、学習の入口として片方だけが突出して有利というわけではありません。
OpenAIのApps SDK周辺でも両方のサンプルが並んでおり、最初の一歩で詰まりにくい点は共通しています。
そのうえで差が出るのは、チームが何を先に作りたいかです。

Pythonが真価を出すのは、まず動くものを素早く作り、ツールの入出力やプロンプトの癖を確かめたい場面です。
MCPサーバーでは、外部APIを叩くだけでなく、CSVやJSONの整形、ログ解析、社内データの前処理のような“少し泥くさい処理”がすぐ隣にあります。
そうした処理を同じ言語でそのままつなげられるので、PoC段階では迂回が減ります。
評価基盤のMCPBenchも Python 3.11 以上を要件に含んでおり、検証系の周辺ツールまで含めるとPython寄りの流れは今も強いままです。

私の感覚でも、MCPのPoCはPythonで始めたほうが前に進みました。
最小の tools/list と tools/call を通し、レスポンス形を見ながら手元のデータ処理コードを足していく流れが自然だったからです。
とくに既存の業務スクリプトや分析用ライブラリがすでに社内にあるなら、その資産をMCPサーバーの裏側へ寄せるだけで試作品になります。
新しいSDKを学ぶ負担より、すでに回っているコードを再利用できる効果のほうが大きい局面は少なくありません。

『MCP Roadmap』を眺めても、MCPの関心は単なるローカル接続から運用面へ広がっていますが、そこへ進む前段の仮説検証ではPythonの速さが効きます。
仕様理解、ツール設計、データ変換の試行錯誤を同時に回す段階では、短いコードで触れる価値がそのまま開発速度に結びつきます。

Roadmap - Model Context Protocol

Our plans for evolving Model Context Protocol

modelcontextprotocol.io

TypeScriptに向く場面

TypeScriptは、Node系の既存基盤やWeb/IDE連携を前提にしたい場合に向いています。
HTTP 層や認証ミドルウェア、構造化ログなどを最初から意識する運用では、TypeScript の型・エコシステムの恩恵が効きます。

TypeScriptが向くのは、Nodeベースの既存基盤に乗せたいときと、WebやIDE連携を初期段階から視野に入れているときです。
MCPサーバーが社内Webサービスの一部として動く、あるいはCursorGitHub Copilotのような開発環境との接続を前提にするなら、HTTP層・認証ミドルウェア・ロギング基盤との接続点をTypeScriptで揃える意味が出てきます。

この相性の良さは、公式ドキュメントや周辺エコシステムの密度にも表れています。
TypeScript SDKはWeb系の開発フローに自然に乗せやすく、IDE補完や型定義の恩恵も受けやすい構成です。
前のセクションで触れたStreamable HTTPへの移行でも、その一貫性が効きます。
TypeScript SDKは v1.10.0 から Streamable HTTP 対応が始まっており、HTTPベースの本番運用へ寄せるときにNode系の知識をそのまま延長しやすい流れができています。

もうひとつTypeScriptが強いのは、将来の本番運用で避けて通れない監査・認証・スケーリングの設計を、Webアプリの延長として扱える点です。
OAuth連携が絡むGitHub APINotion APISlack APIのような統合では、最小権限、トークン管理、HTTPミドルウェア、監査ログの設計が並びます。
MCPサーバーだけを孤立した特殊実装にせず、既存のNode運用基盤へ載せるほうが筋が通るチームは多いはずです。

チーム事情で決める判断フレーム

判断の軸を具体化すると、まず既存資産です。
社内に分析スクリプト、ETL、検証コード、APIラッパーがPythonで積み上がっているなら、その資産をMCPサーバーの内部ロジックとして再利用したほうが立ち上がりは軽くなります。
逆に、認証基盤、バックエンドAPI、フロントエンド周辺の共通ライブラリがNodeで整っているなら、TypeScriptで揃えたほうが構成の見通しが良くなります。

次にチームスキルです。
AI実験に強いメンバーが多いならPythonから入り、HTTP化や認証設計の段階でTypeScriptへ橋を架ける進め方が合います。
Webバックエンドやフロントエンドの担当が中心なら、最初からTypeScriptでMCPの型とHTTP実装を並べたほうが、レビューや保守の分担が明確になります。
言語選定は個人の好みより、誰が障害対応を受け持つかまで含めて見ると判断を誤りません。

運用対象クライアントも見逃せません。
Claude for Desktopへローカル接続して最初の価値を試す段階ではPythonの機動力が活きます。
一方で、CursorやGitHub Copilot、あるいはOpenAIのアプリ統合のように接続先が増えていくと、HTTP基盤との整合性や認証フローの設計が前面に出てきます。
ここではWeb系エコシステムとの噛み合わせがそのまま運用効率につながります。

この整理で見ると、現実解はひとつに固定されません。
Pythonは試作とデータ処理で強く、TypeScriptは公式SDKやWeb運用との接続で筋が良い。
だからこそ、既存資産を優先して入口を決め、将来の監査・認証・スケーリングまで見据えて出口を揃える、という選び方が実務には合っています。

ローカル運用の原則

初心者が最初に事故を起こしやすいのは、機能そのものより「どこまで見えていて、どこまで触れるか」を曖昧なまま進める場面です。
ローカルで試しているつもりでも、不要なポートを開けたままにしたり、認証なしのHTTPエンドポイントを残したりすると、試作のつもりだったものがそのまま露出面になります。
最初の検証をローカルプロセス内に閉じておくのは、実装が単純というだけでなく、外部公開面を増やさないという意味でも筋が通っています。

この段階で意識したいのは、ツールに与える権限を「必要になったら足す」順番で設計することです。
試作では、とりあえず全部読めるファイルツールを置くと動作確認が速いので、ついそこへ流れます。
私も初期の試作でその形を何度も作りましたが、本番へ寄せる段階で「このディレクトリは読めないようにする」「この拡張子だけ許可する」と削っていくと、呼び出し経路も例外処理も崩れて手戻りが増えました。
最初からアクセスルートを限定し、たとえば特定ディレクトリ配下のみ、特定コマンドのみ、特定APIスコープのみ、という形で細く始めたほうが後の移行が軽くなります。

同じ発想で、秘密情報もロジックと分けておく必要があります。
APIキーやトークンをコードに埋め込むと、ローカルの便利さと引き換えに、ログ出力、設定共有、リポジトリへの誤コミットといった別の漏えい経路が生まれます。
MCPサーバーは外部APIとつながることが多く、GitHub APINotion APISlack APIのようにOAuthやスコープ設計を前提にしたサービスでは、秘密情報の分離を後回しにすると認可設計まで巻き込んで崩れます。
ローカル運用では「単体で動けばよい」ではなく、「本番で削らなくて済む形で動くか」を基準に置くほうが、設計の芯がぶれません。

ローカルと公開運用では、求められる防御線も変わります。
ローカルでは権限範囲を狭めることが主戦場ですが、公開に寄せると認証、認可、監査、ログ保全まで一気に要求が増えます。
公開状態のMCPサーバーが機密データへの経路になりうる点が整理されています。
ローカルで許される雑さが、公開ではそのまま侵入口になるという前提で捉えたほうが実態に合います。

次に、ツールごとの権限境界です。
ファイルアクセスなら対象ディレクトリを限定し、コマンド実行なら許可する実行ファイルと引数パターンを固定し、外部APIなら必要なスコープだけに絞ります。
ここで「全部できるトークンを1本だけ持たせる」設計を選ぶと、1つのツール不備が全権限の流出に直結します。
たとえばGitHub APIなら、読み取りだけで足りる場面と、コミットやワークフロー実行まで必要な場面は分けて扱うべきです。
単一の高権限トークンをMCPサーバー全体で共有すると、モデルが呼ぶどのツールからでも同じ権限に触れてしまいます。

入力検証も見逃せません。
MCPサーバーは自然言語からツール呼び出しへ変換されるため、「ユーザー入力がそのまま安全な引数になる」と考えると危険です。
コマンド実行系では、引数を文字列連結で組み立てるだけでコマンドインジェクションの入口になります。
ファイル操作系では、../ を含む相対パスやURLエンコードされた文字列を通すと、想定外の場所へ到達するパストラバーサルにつながります。
対策としては、許可する引数のホワイトリスト化、パスの正規化、絶対パス化したうえで許可ディレクトリ配下かを再判定する手順が基本になります。
「入力値を受け取る」のではなく、「定義済みの選択肢を受け取る」に寄せるだけで、攻撃面は大きく削れます。

1. 外部公開が必要なポートだけを残し、検証用のエンドポイントを閉じている
2. 無認証で叩けるルートが残っていない
3. ファイルアクセス範囲が特定ディレクトリ配下に固定されている
4. 実行可能なコマンドと引数がホワイトリストで定義されている
5. APIトークンが用途別に分かれ、単一の高権限トークンに集約されていない
6. 秘密情報がコードや設定例に直書きされていない
7. 誰が・いつ・どのツールを呼び、結果がどうだったかをログで追える

この一覧は地味ですが、事故の入口をそのまま塞ぐ項目です。公開運用では、機能が足りないことより、境界が曖昧なことのほうが後から大きく響きます。

Transports - Model Context Protocol

modelcontextprotocol.io

実装の勘所：OAuth/最小権限/監査トレイル

外部サービス連携を含むMCPサーバーでは、OAuthや認可委譲を避けて通る構成より、最初から前提に入れた構成のほうが安定します。
理由は単純で、MCPサーバー自身がユーザーの代理でAPIを叩くからです。
ここで固定トークンを1本だけ持たせると、「誰の権限で、どのリソースへアクセスしたのか」が曖昧になります。
OAuthを使えば、利用者ごとの認可とアプリ側の権限を分離でき、必要なスコープだけを明示して委譲できます。
GitHubのOAuthスコープ、NotionのAuthentication、SlackのOAuth v2はいずれも、必要最小限の権限付与を前提に設計されています。

このとき整理しておきたいのが、どのリソースに対する認可なのかという単位です。
複数サービスをまたぐMCPサーバーで、ひとつのトークンに権限を集めると、意図しない横断アクセスが起こります。
Resource Indicatorsの考え方に沿って、対象リソースやAPIごとに認可対象を分けておくと、「このツールはGitHubの読み取りだけ」「このツールはSlackへの投稿だけ」という境界を保てます。
認可委譲の設計を曖昧にしたままツールだけ増やすと、後から権限分離を入れる工事が大きくなります。

ログ設計も、ローカルと公開で意味が変わります。
ローカルなら標準出力に開発ログが出ていれば足りますが、公開ではそれでは追跡が切れます。
必要なのは、誰が、いつ、どのセッションで、どのツールを呼び、どの引数で、成功したのか失敗したのかを後で追える形です。
しかも自由記述のログではなく、JSONなどの構造化ログで残したほうが検索と集計が効きます。
たとえば user_id、session_id、tool_name、resource、status、error_code のように項目を固定しておくと、障害調査だけでなく、不審な呼び出しの検知にも使えます。
監査ログは「読めること」ではなく、「後から並べ替えて追えること」に価値があります。

実装の現場では、認証、認可、入力検証、監査ログは別々の論点に見えますが、実際には一本につながっています。
入力検証が甘いツールに高権限トークンを持たせ、しかも監査ログが自由記述だけだと、事故が起きたあとに経路を復元できません。
逆に、OAuthで権限を委譲し、最小権限に分け、引数をホワイトリストで絞り、構造化ログで呼び出しを残していれば、1つの不備が即座に全面事故へつながる形は避けられます。
公開MCPサーバーでは、この連鎖を最初から断ち切る設計がそのまま品質になります。

よくあるエラーと対処

設定反映の確認ポイント

設定を書き換えたのにツールが見えない、接続したはずのサーバーが一覧に出ない、という場面では、まず「設定ファイルの内容」より先に「クライアントがその変更を読み直したか」を疑うと早いです。
実際に詰まりやすかったのはここで、私の手元でも一番多かったのは完全再起動漏れでした。
設定を書き換えても、常駐プロセスを落とすまで反映されないクライアントは珍しくありません。
Claude for Desktopは設定更新後の再起動が案内されており、バックグラウンドに残ったままだと新しい mcpServers が読まれないまま進みます。
ウィンドウを閉じただけで安心すると、古い設定のまま接続確認を続けることになります。

Cursorでも似た罠があります。
UI上でサーバーを追加したあと、接続状態の表示が更新されるまでに見落としが出やすく、緑のステータスが出ていない段階で「サーバー側が壊れている」と判断しがちです。
こういうときは、設定ファイルのJSONが崩れていないか、追加したサーバー名が意図した項目に入っているか、クライアント側で接続済み表示やツール一覧に変化があるかを順番に見ます。
MCP Inspectorを併用すると、クライアント固有の表示不具合なのか、サーバーそのものが起動できていないのかを切り分けやすくなります。
Model Context Protocol公式のMCP Inspectorは stdio と Streamable HTTP の両方を扱えます。
クライアントに載せる前の単体確認に向いており、ドキュメントに機能概要があります。

設定反映の確認では、見た目の変化だけでなく、認可まわりのダイアログも見逃せません。
ツールが表示されても、クライアント側で未承認のツール呼び出しが止められていると、実行段階で拒否されます。
GitHub Copilot系のMCP連携でも、組織ポリシーや追加のアクセス許可が必要な流れがあり、サーバーが生きていてもクライアント側の許可待ちで止まることがあります。
接続確認は「一覧に出たか」だけでは足りず、「実際に1回ツールを呼べるか」まで見て初めて完了です。

依存関係・パスの健全性チェック

ローカルの stdio 構成で起動しないときは、MCPそのものより command と args の解決に失敗しているケースが多いです。
たとえば python を想定していたのに実際は python3 しか通っていない、仮想環境の実行ファイルを前提にしたのにクライアントはシステムの PATH で起動している、npx を使う設定なのに nvm 配下のNodeがGUIアプリから見えていない、という形です。
端末では動くのにClaude for DesktopやCursorからだけ失敗するなら、まずこのズレを疑います。

Python系なら仮想環境の有効化に頼った起動が崩れやすく、Node系なら nvm の初期化がシェル設定に閉じているため、GUI起動したアプリから node や npx が見えないことがあります。
PATH に依存した短いコマンド名で登録するより、実行ファイルの絶対パスを使ったほうが切り分けは早く進みます。
MCPBenchが Python 3.11 以上を要件にしているように、周辺ツールでも実行系のバージョン前提は無視できません。
サーバー実装が新しめのSDKに寄っているほど、手元のランタイム差分がそのまま起動失敗になります。

環境変数も詰まりどころです。
OPENAI_API_KEY、GITHUB_TOKEN、NOTION_API_KEY のような秘密情報がシェルには入っていても、デスクトップアプリの子プロセスには渡っていないことがあります。
結果として、サーバー自体は起動したように見えて、最初のAPI呼び出しで認証エラーになります。
ファイル権限も同じで、設定ファイルは読めるのに、実際に触るディレクトリや秘密情報ファイルにアクセスできず落ちることがあります。
ここはMCPの抽象論で眺めるより、which python や which node に相当する実体確認、環境変数の有無、対象ファイルの読み取り権限という3点で見ると詰まりがほどけます。

トランスポート別の典型落とし穴

stdio で最も多いのは、stdout にログを混ぜてしまうことです。
MCPメッセージの通り道に人間向けログを流すと、クライアントはプロトコルの応答として解釈できず失敗します。
デバッグ時に print() を足しただけで接続不能になるのはこの典型で、開発ログは stderr に分けるだけで挙動が安定します。
ローカルでは「少しログが増えただけ」に見えても、stdio ではその1行が通信破壊になります。

未承認ツール呼び出しも、stdio 構成で誤解されやすい点です。
サーバーが tools/list を返していても、クライアントがそのツールを自動実行してよいとは限りません。
許可ダイアログを閉じたまま、あるいはポリシーでブロックされたままにしていると、モデルは呼ぼうとしても実行されません。
ここではサーバー側ログだけ見ても答えが出ず、クライアントの許可状態、セッション状態、認証済みかどうかまで見る必要があります。
OAuth連携ツールでは、セッションや認証設定が不足しているだけで「ツール一覧には出るが使えない」という半端な状態になります。

Streamable HTTP に移ると、今度はエンドポイントとヘッダーの取り回しで詰まります。
旧来のHTTP+SSE前提のサンプルを流用すると、エンドポイント分離のつもりで構成したまま新しい実装と噛み合わず、接続確立後のやり取りが続きません。
TypeScript SDK は v1.10.0 で Streamable HTTP 対応が始まっており、比較的新しい実装前提で読む必要があります。
ここで特に見落としやすいのが Mcp-Session-Id です。
セッション継続にこのヘッダーを使う構成では、最初の応答で受け取った値を後続リクエストへ正しく渡さないと、毎回新規セッション扱いになったり、途中から無効セッションとして拒否されたりします。
HTTPステータスだけ追っていると「200は返るのに会話が続かない」という見え方になり、原因に気づきにくいところです。

HTTP系では認証ヘッダー不足も同時に起こりがちです。
BearerトークンやAPIキーが欠けている、プロキシ越しに必要なヘッダーが落ちている、CORSやリバースプロキシ設定で想定した経路になっていない、といった問題は、stdioの感覚のまま移行すると見逃します。
トランスポートを変えるとデバッグの主戦場も変わり、stdioでは標準入出力の整合性、Streamable HTTPではセッションID・認証ヘッダー・エンドポイント設計が中心になります。
同じMCPサーバーでも、つまずく場所はまったく別物です。

まとめ｜次に作るべきMCPサーバー例

まず作るなら、Filesystemや weather 系のように、ツール範囲とアクセス先を絞れる最小構成が向いています。
私自身も読み取り専用ディレクトリだけを触るFilesystemから始め、事故を避けながら「どこまで仕事になるか」を確かめました。
小さく切った実装は、あとでNotionGitHubSlackへ広げるときも設計を載せ替えやすく、無駄になりません。

次に進む先は、認証が入る実案件です。
Notion APIやSlack API、GitHub APIのOAuth設計を先に見て、OAuth、最小権限、監査ログを決めてから着手すると、後戻りを減らせます。
チーム利用を見据えるならGitHub Copilotでも扱いやすい .vscode/mcp.json を整えます。
将来の本番候補として Streamable HTTP 化まで道筋を描いておくと進め方がぶれません。

次に進む先は、認証が入る実案件です。
Notion APIやSlack API、GitHub APIのOAuth設計を先に見て、OAuth、最小権限、監査ログを決めてから着手すると、後戻りを減らせます。
チーム利用を見据えるならGitHub Copilotでも扱いやすい .vscode/mcp.json を整えます。
将来の本番候補として Streamable HTTP 化まで道筋を描いておくと進め方がぶれません。