MCPサーバーの作り方|TypeScriptで自作しCodexにつないだ27回の検証
MCPサーバーの作り方を、TypeScript SDK v2(@modelcontextprotocol/server 2.4.0)で最小のサーバーを書き、Codex CLIにつなぐまで実機で解説。27回の実行で分かった、AIがツールを使えない原因(起動待ち・承認・パス)と、答えの抜けを減らす書き方も載せます。

MCPサーバーは、TypeScriptなら @modelcontextprotocol/server を入れ、registerTool() でツールを1つ登録し、serveStdio() で起動するだけで作れます。編集部が2026年10月26日に、自作のサーバーを Codex CLI 0.163.0 につないで27回試したところ、正しく起動できた回はAIがツールを毎回呼び、結果をそのまま答えに使いました。一方で、起動に3秒かかるサーバーは3回中2回、ツールとして見えませんでした。承認を prompt にした設定では codex exec からの呼び出しが2回とも失敗し、サーバーのパスを間違えても警告は出ませんでした。
MCPサーバーとは、AIアプリ(Codex、Claude、ChatGPTなど)に、外部のデータや機能を「ツール」として渡すプログラムです。MCP(Model Context Protocol)は、AIアプリを外部のシステムにつなぐための公開の標準で、公式サイトは「AIアプリのためのUSB-Cポート」とたとえています。
本記事は、Codex CLIの基本(インストール・codex exec)を扱ったCodex CLIの使い方の続きです。Claude Codeにつなぐ場合の設定(claude mcp add・スコープ・.mcp.json)はClaude CodeのMCP設定方法、Codexそのものの比較はCodexとClaude Codeを比較、作業の手順をAIに教える別の標準はAgent Skillsとはで説明しています。
結論:作り方の早見表と、つまずいた点
下の表は、公式ドキュメントの手順と、編集部が実際に動かして確かめた結果をまとめたものです。
| やること | コマンド・設定 | 検証で分かったこと |
|---|---|---|
| SDKを入れる | npm install @modelcontextprotocol/server zod |
2.4.0 と zod 4.6.7 で動作。Node.js 24 なら .ts をそのまま実行できた |
| サーバーを起動する | serveStdio(createServer) |
READMEの例の server.connect() は、2026-07-28版の接続方法に応答しなかった(Codex 0.163.0 では両方動いた) |
| ツールを登録する | server.registerTool('名前', { description, inputSchema }, 処理) |
AIは説明文を読んで呼ぶ。結果に無いものは答えにも出なかった |
| 使い方をAIに伝える | new McpServer(情報, { instructions }) |
「言い換えでも検索する」と書くと、答えに入った記事が2本→5本に増えた |
| Codexに登録する | codex mcp add 名前 -- node /絶対パス/server.ts |
~/.codex/config.toml に [mcp_servers.名前] が書かれる |
| 呼ばれたか確かめる | codex exec --json "質問" |
mcp_tool_call の行にツール名・引数・結果が出る |
| 起動が遅いサーバー | mcp_optional_startup_grace_ms = 0 |
既定(1000ミリ秒)のままだと、3秒かかるサーバーは3回中2回使えなかった |
| ツールの承認 | default_tools_approval_mode |
prompt にすると、codex exec では2回とも失敗した |
| 起動に失敗したら止める | required = true |
パスを間違えると0.27秒で終了し、原因が表示された |
MCPサーバーとは(1分で)
MCPサーバーは、AIアプリの外で動く小さなプログラムです。AIアプリ(MCPの用語ではホスト)は、起動時にサーバーへ「どんなツールがあるか」を尋ね、会話の中で必要だと判断したときにツールを呼びます。サーバーは結果を返すだけで、どのツールをいつ呼ぶかはAIが決めます。
つなぎ方は2つあります。
- stdio:AIアプリがサーバーをローカルのプロセスとして起動し、標準入出力でやりとりする。本記事はこちら。
- Streamable HTTP:サーバーをURLで公開し、HTTPでやりとりする。社外のサービスにつなぐときはこちらが多い。
OpenAIの公式ドキュメントによると、Codex CLI・IDE拡張・ChatGPTのデスクトップアプリは、同じ config.toml のMCP設定を共有します。CLIで登録したサーバーは、ほかの2つでもそのまま使えます。
検証した環境と方法
数字はすべて、編集部が自分の環境で走らせた実行ログから取りました。
- 日付:2026年10月26日(日本時間14時13〜27分に27回)
- 環境:Linux(x64)、Node.js 24.22.1
- SDK:
@modelcontextprotocol/server2.4.0(2026年10月23日公開)、zod 4.6.7 - Codex CLI:0.163.0、ChatGPTでサインイン。モデルは指定なし(実行記録上は全回
gpt-6.1-sol) - 実行:
codex exec --json、読み取り専用のサンドボックス、Web検索なし。毎回、空のディレクトリで実行 - 題材:このサイト(AIみちしるべ)の記事を検索するツール
search_articles。記事は2026年10月26日時点の32本のコピーを使いました - 質問:全回同じ「AIみちしるべの記事のうち、不動産に関する記事を公開日つきで一覧にしてください」。不動産会社向けの記事は5本あり、タイトルか説明文に「不動産」を含むのはそのうち2本です
サーバーのコード・実行スクリプト・数値データは、記事末尾の「参考にした公式情報」に場所を書いています。
作り方:TypeScriptで最小のMCPサーバーを作る
ここからは、記事を検索するツールを1つだけ持つサーバーを作り、Codexにつなぎます。
1. プロジェクトを作り、SDKを入れる
空のフォルダで npm init -y を実行し、package.json に "type": "module" を足してから、npm install @modelcontextprotocol/server zod でSDKを入れます。
$ mkdir michishirube-mcp && cd michishirube-mcp
$ npm init -y
$ npm pkg set type=module
$ npm install @modelcontextprotocol/server zod
$ npm install -D typescript @types/node
公式のREADMEによると、2026年7月にSDKのv2が出て、パッケージ名が @modelcontextprotocol/sdk から @modelcontextprotocol/server(サーバー用)と @modelcontextprotocol/client(クライアント用)に分かれました。v1は少なくとも6か月、不具合と安全性の修正が続きます。検索で見つかる解説の多くはv1の書き方です(後述)。
2. ツールを1つ登録する
server.ts に、McpServer を作って registerTool() でツールを登録する関数(createServer)と、それを serveStdio() で起動する1行を書きます。編集部が実際に使った最終版のコードです。
// AIみちしるべの記事を検索する最小の MCP サーバー(stdio)
import { readdir, readFile } from 'node:fs/promises';
import { join } from 'node:path';
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
const ARTICLES_DIR = process.env.ARTICLES_DIR ?? './articles';
type Meta = { slug: string; title: string; description: string; date: string; updated: string; category: string };
// 記事の Markdown 先頭(--- で囲まれた部分)から必要な項目だけ読む
async function loadArticles(): Promise<Meta[]> {
const files = (await readdir(ARTICLES_DIR)).filter((f) => f.endsWith('.md'));
const list: Meta[] = [];
for (const f of files) {
const text = await readFile(join(ARTICLES_DIR, f), 'utf8');
const head = text.split('\n---')[0];
const get = (k: string) => head.match(new RegExp(`^${k}:\\s*(.+)$`, 'm'))?.[1].trim() ?? '';
list.push({ slug: f.replace(/\.md$/, ''), title: get('title'), description: get('description'), date: get('date'), updated: get('updated'), category: get('category') });
}
return list.sort((a, b) => b.date.localeCompare(a.date));
}
// 接続ごとに新しいサーバーを返す(serveStdio がこの関数を呼ぶ)
function createServer() {
const server = new McpServer(
{ name: 'michishirube', version: '1.0.0' },
{ instructions: 'search_articles は語の完全一致で探す。該当が少ないときは、言い換え(例: 不動産→賃貸・物件・入居者)でも検索してから答える。' },
);
server.registerTool(
'search_articles',
{
description: 'AIみちしるべ(ai.sanvia.co.jp)の記事を検索する。キーワードをタイトル・説明文・カテゴリから探し、該当件数と、各記事の公開日・更新日・URLを返す。',
inputSchema: z.object({
keyword: z.string().describe('探す語。例: 不動産, Codex'),
}),
annotations: { readOnlyHint: true },
},
async ({ keyword }) => {
const all = await loadArticles();
const hits = all.filter((a) => (a.title + a.description + a.category).toLowerCase().includes(keyword.toLowerCase()));
console.error(`[michishirube] search_articles keyword=${keyword} hits=${hits.length}`); // ログは stderr へ
const lines = hits.map((a) => `- ${a.title}(公開 ${a.date}${a.updated ? `/更新 ${a.updated}` : ""})https://ai.sanvia.co.jp/articles/${a.slug}`);
const summary = `全${all.length}件中${hits.length}件が該当(タイトル・説明文・カテゴリを検索)`;
return { content: [{ type: 'text', text: [summary, ...lines].join('\n') }] };
},
);
return server;
}
serveStdio(createServer, { onerror: (e) => console.error('[michishirube] error:', e) });
console.error('[michishirube] ready'); // stdout には何も書かない
ポイントは4つです。description はAIがツールを選ぶときに読む説明なので、何を探し何を返すかを具体的に書きます。inputSchema はzodで書き、AIが送る引数の形を決めます。annotations の readOnlyHint: true は「このツールは何も書き換えない」という目印で、Codexの承認の設定(後述)で使われます。instructions は、接続時にAIへ渡すサーバー全体の使い方で、この1文が答えの抜けを減らしました(後述)。
起動に serveStdio() を使うのは、公式チュートリアルの書き方に合わせるためです。チュートリアルによると、serveStdio() は接続してきたクライアントごとに通信の版(2026-07-28版か、2025年版か)を合わせます。READMEの最小例にある server.connect(new StdioServerTransport()) もコンパイルは通りますが、2025年版のクライアントにしか応答しません。そのため createServer は、呼ばれるたびに新しい McpServer を返す関数にしています。
Node.js 24では、この .ts ファイルを node server.ts でそのまま実行できました(型を外して実行する機能)。古いNode.jsを使う場合は npx tsc でJavaScriptに変換してから実行します。
3. AIを使わずに動作を確かめる
Codexにつなぐ前に、SDKのクライアント(@modelcontextprotocol/client)でサーバーを起動し、ツールの一覧取得と呼び出しができるかを確かめます。
編集部は10回試し、起動から接続完了までが中央値0.16秒(0.15〜0.20秒)、一覧の取得とツールの呼び出しが中央値0.02秒でした。ここで動かないときは、AIの問題ではなくサーバーの問題です。
公式チュートリアルは、確認ツール MCP Inspector のコマンド版で、新旧両方の接続方法を試すよう勧めています。編集部の結果は次のとおりです。
$ npx @modelcontextprotocol/inspector --cli node server.ts --protocol-era modern --method tools/list
→ serveStdio 版:search_articles が返る(legacy でも同じ)
→ server.connect() 版:Version negotiation failed: the server did not offer pinned protocol version 2026-07-28 via server/discover (no fallback in pin mode)
server.connect() 版は、--protocol-era legacy(2025年版)では一覧を返しました。Codex CLI 0.163.0 は両方の版で動いたので、Codexだけで試すとこの違いに気づけません。
4. Codex CLIに登録する
codex mcp add 名前 -- 起動コマンド で登録します。環境変数は --env で渡せます。パスは絶対パスで書きます。実際の出力です(パスは短くしています)。
$ codex mcp add michishirube --env ARTICLES_DIR=/path/to/articles -- node /path/to/server.ts
Added global MCP server 'michishirube'.
$ codex mcp list
Name Command Args Env Cwd Status Auth
michishirube node /path/to/server.ts ARTICLES_DIR=***** - enabled Unsupported
このとき ~/.codex/config.toml に次の設定が書き込まれました。ファイルを直接編集しても同じです。プロジェクトの中の .codex/config.toml に書けば、そのプロジェクトだけで使えます(信頼済みのプロジェクトのみ)。
[mcp_servers.michishirube]
command = "node"
args = ["/path/to/server.ts"]
[mcp_servers.michishirube.env]
ARTICLES_DIR = "/path/to/articles"
編集部は普段の設定を変えないよう、登録の確認は使い捨ての設定フォルダ(CODEX_HOME)で行い、27回の実行では同じ内容を codex exec -c mcp_servers.michishirube.command=... の形で毎回渡しました。
5. codex exec で呼ばれたか確かめる
codex exec --json "質問" を実行し、出力に mcp_tool_call の行があるかを見ます。実際のログの一部です(読みやすく改行しています)。
{"type":"item.completed","item":{"type":"mcp_tool_call",
"server":"michishirube","tool":"search_articles",
"arguments":{"keyword":"不動産"},
"result":{"content":[{"type":"text","text":"全32件中2件が該当(タイトル・説明文・カテゴリを検索)\n- 不動産の反響メール返信をAIで下書き|…"}]},
"status":"completed"}}
対話モード(codex)では、/mcp で接続中のサーバーを確認できます。
実測:27回で分かったこと
条件を変えて27回試した結果が次の図です。最終版以外の条件は、上のコードから instructions を外し、server.connect() で起動する版にしかけを足して試しました。棒は、検索ツールの結果をAIが受け取れた回数です。右の数字は、最終的な答えに入った不動産の記事の数(正解は5本)です。
| 条件 | 回数 | ツールの結果を受け取れた回数 | 答えに入った不動産の記事(5本中) | 1回の所要時間(中央値) |
|---|---|---|---|---|
| 最初の版(タイトルとカテゴリだけ検索) | 3 | 3 | 各2本 | 12.1秒 |
| 説明文も検索し、件数を返す | 3 | 3 | 各2本 | 13.0秒 |
| +サーバーの instructions | 3 | 3 | 各5本 | 16.5秒 |
| 最終版(上のコード:serveStdio+instructions) | 3 | 3 | 各5本 | 17.5秒 |
| 起動に3秒かかる(既定の設定) | 3 | 1 | 0・0・2本 | 13.5秒 |
起動に3秒+mcp_optional_startup_grace_ms=0 |
3 | 3 | 各2本 | 14.6秒 |
stdoutに console.log(起動時・処理中) |
4 | 4 | 各2本 | 16.2秒 |
default_tools_approval_mode="prompt" |
2 | 0 | 0本 | 13.7秒 |
| サーバーのパスを間違える | 2 | 0 | 0本 | 13.6秒 |
パス間違い+required=true |
1 | 0 | ―(実行前に終了) | 0.27秒 |
AIはツールの結果をそのまま信じる
最初の版と、説明文も検索する版では、AIは「不動産」で1回だけ検索し、見つかった2本を答えました。残りの3本(物件紹介文・入居者へのお知らせ・賃貸管理の記事)は、タイトルにも説明文にも「不動産」という語がありません。AIは別の語で探し直さず、ツールの結果だけで答えを作りました。「全32件中2件が該当」と件数を返しても、追加の検索はしませんでした。
サーバーの instructions に「該当が少ないときは、言い換え(例:不動産→賃貸・物件・入居者)でも検索してから答える」と1文書くと、3回とも4〜6回検索し、5本すべてを答えました。最終版のコードでも3回とも4回検索し、5本を答えています。OpenAIの公式ドキュメントは、Codexがこの欄を読むこと、大事なことは最初の512文字に書くことを勧めています。
また、1回だけ、AIが最初に引数名を keyword ではなく query で送り、入力チェックのエラーを受け取ってから正しい名前で呼び直しました。zodの入力チェックが、誤った呼び出しをはじいて、AIに直させた形です。
起動が1秒より遅いと、ツールが見えないことがある
Codexは、必須でない(required を付けていない)MCPサーバーを、最初のツール一覧を作るときに既定で1000ミリ秒だけ待ちます(設定名 mcp_optional_startup_grace_ms)。起動に3秒かかるようにしたサーバーでは、3回中2回、AIは検索ツールを一度も呼べず、「この環境ではWebサイトにアクセスできず、記事を確認できません」と答えました。残りの1回は、先に別のコマンドを実行したあとでツールを呼べました(理由は未確認)。
mcp_optional_startup_grace_ms = 0 にすると、各サーバーの startup_timeout_sec(既定10秒)まで待つようになり、3回ともツールを使えました。データベースへの接続など、起動に時間がかかるサーバーではこの設定か required = true を検討してください。
承認を prompt にすると、codex exec では失敗する
default_tools_approval_mode = "prompt" は、ツールを使うたびに人の承認を求める設定です。対話のない codex exec では承認を出せないため、2回ともツールの呼び出しが失敗しました。ログのエラーは MCP tool call requires approval, but approval policy is never で、AIは「承認が必要で取得できませんでした」と答えました。
公式ドキュメントによると、値は auto・prompt・writes・approve の4つで、writes は「読み取り専用の印(readOnlyHint)がないツールだけ承認を求める」です。自動化で使うサーバーは、書き換えをしないツールに readOnlyHint: true を付けておくと、承認の設定と組み合わせやすくなります。
パスを間違えても、警告は出なかった
サーバーのパスを存在しないファイルにすると、AIはツールを使えず、Codex内蔵の別のツールやcurlを試したあと「アクセスできません」と答えました。このとき、--json の出力にも通常の画面表示にも、サーバーの起動に失敗したという警告は出ませんでした。終了コードも0です。
required = true を付けると、同じ間違いで0.27秒で終了し(終了コード1)、required MCP servers failed to initialize: michishirube: handshaking with MCP server failed と原因が表示されました。CIなど、人が画面を見ない使い方では required = true を付けておくと、失敗に気づけます。
stdout に書いても、今回は壊れなかった(それでも書かない)
MCPの仕様は、stdioのサーバーが標準出力(stdout)にMCPのメッセージ以外を書くことを禁止しています。公式のチュートリアルも「console.log() は使わない、console.error() を使う」と書いています。
編集部が起動時と処理中に console.log で1行書いてみたところ、Codex CLI 0.163.0 でも、SDKのクライアント2.4.0でも、4回とも問題なく動きました。ただし、これは今回の版と今回の文字列での結果です。JSONに見える行や、ほかのクライアントでどうなるかは確かめていません。ログは console.error()(stderr)に出す、が安全です。
古い解説記事との違い(SDK v1 と v2)
「MCPサーバー 作り方」で上位に出るページを2026年10月26日に11本読んだところ、TypeScriptの4本は、いずれもv2の @modelcontextprotocol/server ではなく、server.tool() や低レベルの Server クラスで書かれていました。公開日は2025年3月〜7月が中心です。Codexにつなぐ手順を載せたページは、自作のサーバーではなく既存のサーバーを登録する内容でした。
| 項目 | 古い解説に多い書き方(v1) | 本記事(v2) |
|---|---|---|
| パッケージ | @modelcontextprotocol/sdk |
@modelcontextprotocol/server(クライアントは @modelcontextprotocol/client) |
| ツールの登録 | server.tool(名前, スキーマ, 処理) |
server.registerTool(名前, { description, inputSchema }, 処理) |
| 起動 | server.connect(new StdioServerTransport()) |
serveStdio(createServer)(新旧両方の接続方法に応答) |
| スキーマ | zod 3 | zod 4(zod/v4)。Standard Schema に対応した Valibot・ArkType も可 |
| つなぐ先 | Claude Desktop・Cursor | Codex CLI(codex mcp add/config.toml) |
v1の書き方がすぐ動かなくなるわけではありません。公式のREADMEは、v1の不具合と安全性の修正を、v2の公開(2026年7月27日)から少なくとも6か月続けるとしています。これから新しく作るなら、v2で始めるのが無難です。
Codexの主な設定項目
config.toml の [mcp_servers.名前] に書ける主な項目です(OpenAIの公式ドキュメント、2026年10月26日に確認)。
| 項目 | 意味 | 既定 |
|---|---|---|
command・args |
サーバーを起動するコマンドと引数(stdio) | ― |
env・env_vars |
渡す環境変数(値を書く/手元の変数を引き継ぐ) | ― |
url |
Streamable HTTP のサーバーのURL | ― |
startup_timeout_sec |
起動を待つ秒数 | 10秒 |
tool_timeout_sec |
ツールの実行を待つ秒数 | 60秒 |
required |
起動に失敗したら Codex も止める | 付けない |
enabled_tools・disabled_tools |
使うツール・使わないツールの一覧 | ― |
default_tools_approval_mode |
承認(auto・prompt・writes・approve) |
― |
mcp_optional_startup_grace_ms(最上位) |
必須でないサーバーを最初に待つ時間 | 1000ミリ秒 |
default_tools_approval_mode の既定値は、公式ドキュメントに書かれていませんでした。編集部の環境で何も指定しなかった回は、codex exec でも承認なしで呼べました。
まだ確かめていないこと
- Claude Code・Claude Desktop・Cursorでの動作(まだ試していません)。
- Streamable HTTPのサーバー、OAuthでのログイン、Windowsでの登録。
- 対話モードで承認を求められたときの画面。
tool_timeout_secを超えたとき、AIがどう答えるか。- 起動に3秒かかるサーバーで、1回だけツールを呼べた理由。
社内のどのデータやシステムをAIにつなぐと効果が出るかを先に整理したい場合は、AI 導入診断で、業務ごとの始めどころを確認できます。
よくある質問
Q. MCPサーバーとは何ですか?
AIアプリに、外部のデータや機能をツールとして渡すプログラムです。MCP(Model Context Protocol)という公開の標準に沿って話すので、一度作れば Codex や Claude など、MCPに対応した複数のAIアプリから使えます。
Q. MCPサーバーはどの言語で作れますか?
公式チュートリアルには、TypeScript・Python・Java・Kotlin・Go・Rustなど、複数の言語の手順があります(2026年10月26日に確認)。本記事はTypeScriptのSDK v2(@modelcontextprotocol/server 2.4.0)で作りました。
Q. 自作したMCPサーバーをCodexで使うには?
codex mcp add 名前 -- node /絶対パス/server.ts で登録します。設定は ~/.codex/config.toml の [mcp_servers.名前] に保存され、Codex CLI・IDE拡張・ChatGPTのデスクトップアプリで共有されます。
Q. MCPサーバーを登録したのに、AIがツールを使いません。
編集部の検証では、起動に1秒以上かかるサーバー、承認を prompt にした設定、パスの間違いで、AIはツールを使えませんでした。パスを間違えても警告は出なかったため、required = true を付けて起動の失敗に気づけるようにし、遅いサーバーは mcp_optional_startup_grace_ms = 0 を試してください。
Q. console.log を使うとMCPサーバーは壊れますか?
MCPの仕様は、stdioのサーバーが標準出力にMCPのメッセージ以外を書くことを禁止しています。編集部の検証(Codex CLI 0.163.0)では1行書いても動きましたが、ほかの環境で壊れない保証はありません。ログは console.error で標準エラー出力に出してください。
参考にした公式情報
仕様は変わることがあるため、最新情報は公式で確認してください。取得日はいずれも2026年10月26日(日本時間)です。
- Model Context Protocol(MCPとは)(新しいウィンドウで開く):定義とUSB-Cのたとえ。
- Build an MCP server(公式チュートリアル)(新しいウィンドウで開く):TypeScriptの手順、serveStdio と Inspector での確認、stdioでのログの注意。
- Transports(MCP仕様 2025-11-25)(新しいウィンドウで開く):stdioのサーバーがstdoutに書いてよいもの。
- MCP TypeScript SDK(GitHub)(新しいウィンドウで開く):v2のパッケージ構成、v1の保守期間。
- MCP(Codex 公式ドキュメント)(新しいウィンドウで開く):codex mcp add、config.tomlの項目と既定値、instructions。
- 一次データ(本記事の実測):サーバー
scripts/experiments/mcp-codex/server.ts、実行スクリプトscripts/experiments/mcp-codex-runs.mjs、数値データdata/experiments/2026-10-26-mcp-codex-runs.json(方法と制限は同名の.md)、AIを使わない確認data/experiments/2026-10-26-mcp-sdk-client-check.json。


