MCPサーバーの作り方

サーバー側を自分で建てて、クライアントに登録するまでの最短経路。

MCPサーバーは「ツール一覧を返し、呼ばれたら結果を返す」だけのプロセスです。公式の TypeScript SDK で最小構成を作り、stdio 経由でクライアントに登録します。このページのコードは検証環境で実際に起動・呼び出しまで確認しました。

対象: @modelcontextprotocol/sdk
確認した版: 版: 1.30.0
確認日: 確認日: 2026-09-17

この環境で確かめたこと

SDK で建てた最小サーバー (echo ツール 1 本) に検証クライアントから接続し、initialize → tools/list → tools/call が往復した
Claude Code の設定ファイル ~/.claude.json が mcpServers キーでサーバー定義を持つことを実ファイルで確認した
Codex CLI の codex mcp add が ~/.codex/config.toml に [mcp_servers.<名前>] テーブルを書き、codex mcp list で enabled と出ることを確認した

確認環境: macOS arm64 / Node 26 / Claude Code 2.1.81 / Codex CLI 0.144.3

クライアント別の対応状況

同じサーバーでもクライアントごとに確認の深さが違います。確かめていないものは「未観測」と出します。

検証項目	Claude Code2.1.81	Codex CLI0.144.3	Cursor未導入	VS Code未導入	検証クライアントNode 26 / SDK 1.30.0
設定ファイルへの登録Claude Code は ~/.claude.json の mcpServers 形式を確認。Codex は codex mcp add で config.toml に書き込まれることを確認。	一部確認	確認済み	未観測	未観測	—
stdio での initialize / tools 応答SDK 製クライアントでの往復は確認済み。各 AI クライアント越しの呼び出しは未観測。	未観測	未観測	未観測	未観測	確認済み
リモート (HTTP) 接続Claude Code の mcpServers に type: "http" + url の実在定義を確認済み。実際のリモート接続は未観測。	一部確認	未観測	未観測	未観測	—

確認済みこの環境で再現確認
一部確認一部だけ確認
未観測この環境では試していない
失敗を確認失敗を再現して確認

クライアント別の設定手順

使っているツールのタブを選んでください。手順を終えたら各ステップのボタンで記録できます。

設定の置き場: ~/.claude.json (mcpServers)

この環境の実ファイルに mcpServers 定義があり、形式を確認済み。

サーバーを作る

公式 SDK の McpServer にツールを登録し、StdioServerTransport で待ち受ける最小構成。

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: "my-mcp", version: "0.1.0" });

server.registerTool(
  "echo",
  { description: "渡した文字をそのまま返す", inputSchema: { text: z.string() } },
  async ({ text }) => ({ content: [{ type: "text", text }] }),
);

await server.connect(new StdioServerTransport());

2
Claude Code に登録する
claude mcp add で登録するか、~/.claude.json の mcpServers に直接書く。
ターミナル
```
claude mcp add my-mcp -- npx tsx /path/to/server.ts
```

接続テスト: Claude Code での確認

クライアントの MCP 一覧に自分のサーバーが出て、ツール名 (ここでは echo) が見えれば接続できている。Codex では codex mcp list の Status が enabled になることを確認済み。

ターミナル

codex mcp list          # Status 列が enabled なら登録成功 (確認済み)
claude mcp list        # Claude Code 側の一覧 (ログイン済み環境で実行)

権限・認証スコープ

stdio 接続: 認証なし。クライアントが子プロセスとして起動するため、設定ファイルの command/args を書けることが実質の権限。
環境変数: トークン等は設定の env に書くと子プロセスへ渡る。設定ファイルは平文なので、入れる値の管理に注意。
リモート (HTTP) 接続: ホスト側の OAuth 保護リソースに従う。Figma/Notion のガイドに実測した challenge 例あり。

既知の失敗

実際に観測した失敗だけを載せます。再現できていないものは「未観測」と書きます。

claude mcp add が応答しない
ログイン・初期設定が済んでいない HOME で実行したところ、40 秒待っても終了せず .claude.json も書かれなかった。対話ログイン済みの環境で使うか、設定ファイルを直接書く。
対処: ~/.claude.json の mcpServers に JSON で直接登録する (形式は確認済み)。
npx 経由サーバーの初回 handshake がタイムアウトする
@notionhq/notion-mcp-server を初めて npx で起動した際、パッケージ取得中は initialize に応答せず 25 秒でタイムアウトした。2 回目 (キャッシュ済み) は即応答。
対処: 先に npx -y <パッケージ> を一度素で実行してキャッシュを温める。

隣のガイド

MCP ハブ (サーバー目録) に戻る

最終確認2026-09-17SDK 往復・登録経路は確認済み

サーバーの往復は検証クライアントで確認。各 AI クライアントの画面越しの呼び出しは未観測。バージョンが変わったら testedVersion と lastTestedAt を更新して再テストする。