AI 活用記事AIコーディングツール

MCPサーバーの作り方|TypeScriptで自作しCodexにつないだ27回の検証

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

AIコーディングツール、、読了時間:26分

霧の出た晩秋の杉林で、苔むした岩肌から湧く水を、古い竹の樋が木の支えに乗って運び、苔の付いた丸い石の水鉢へ細くまっすぐ落としている

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/server 2.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本)です。

自作MCPサーバーをCodexにつないだ結果。最初の版は3回中3回ツールを使えて記事は各2本、説明文も検索して件数を返す版も3回中3回で各2本、instructionsで言い換えも検索させると3回中3回で各5本、serveStdioとinstructionsの最終版も3回中3回で各5本。起動に3秒かかるサーバーは既定の設定で3回中1回、grace_msを0にすると3回中3回。stdoutにconsole.logを書いても4回中4回。承認をpromptにすると2回中0回、サーバーのパスを間違えると2回中0回
条件ごとの結果。出典: 編集部の検証(2026年10月26日、Codex CLI 0.163.0、計27回)
条件 回数 ツールの結果を受け取れた回数 答えに入った不動産の記事(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日(日本時間)です。

自社の業務にどのAIツールの使い方が合うか、約3分で確かめる

全8問に答えると、AI 導入の準備度と、最初に試す活用アイデアがわかります。無料・登録不要です。

関連記事

すべてを表示