MCPサーバーの作り方|自作してClaude Codeで使う手順を解説

社内の手順書やデータをClaude Codeに使わせたいとき、毎回ファイルを渡したり本文を貼り付けたりすると手間がかかります。ほかの人のPCでも同じように使ってもらうなら、AIのアプリが自分から読みに来る入口を用意するのが近道です。
この記事では、MCPサーバーをTypeScriptで自作し、Inspectorで確かめてClaude Codeから使うまでの手順を解説します。コードは、株式会社メリルが社外に配っているサーバーと同じ作りです。記事を読めば、自分のMCPサーバーを今日から作れます。
作るときの鍵は、ツールの説明に「いつ使うか」を書くことと、サーバーのソースが無いフォルダから確かめることです。
MCPサーバーの作り方の全体像

MCP(Model Context Protocol)は、AIのアプリに外の道具やデータをつなぐための決まりです。MCPサーバーは、AIのアプリから呼ばれると、決まった形で結果を返します。MCPサーバーがAIのアプリに渡せるものは、以下の表の3種類です。
| 種類 | 渡すもの | 使われ方 |
|---|---|---|
| ツール(Tools) | AIが呼べる処理 | AIが呼ぶ(人の承認つき) |
| リソース(Resources) | ファイルのように読めるデータ | AIのアプリが読む |
| プロンプト(Prompts) | 決まった作業のために、あらかじめ書いた指示のひな形 | 人が作業に使う |
AIのアプリとのつなぎ方は、同じPCで動かす標準入出力(stdio)と、ネットワークの先に置くHTTPの2つです。最初は標準入出力で作って手元で確かめ、社外に配るときにHTTPの入口を足します。MCPのSDKの手順が用意されている言語は、Python・TypeScript・Java・Kotlin・C#・Ruby・Rust・Goの8つです。
この記事では、ツールだけを持つ「手順書を配るサーバー」をTypeScriptで作ります。メリルでは、zipで配っていた記事の手順書を、MCPサーバーから返す形に変えました。2026年8月11日に設計を書き、9日後の8月20日に社外から使える形で開通し、今は4つの手順書を配っています。サーバーが持つツールは、以下の表の3つです。
| ツール | 返すもの | AIが使う場面 |
|---|---|---|
| list_skills | 手順書の名前と、どんな依頼のときに使うかの一覧 | 依頼に合う手順書があるかを確かめるとき |
| get_skill | 手順書の本文(SKILL.md) | 選んだ手順書で作業を始める前 |
| get_skill_file | 手順書と同じフォルダの別のファイル | 本文が例や表を読むように書いているとき |
手順書を直せば、利用者のAIが次に読みに来たときから、全員が新しい版を使います。この記事では、メリルのサーバーと同じ3つのツールを、TypeScriptの約100行で書きました。作る手順は、以下の5つです。
- MCPサーバーを作る準備をする
- ツールを持つMCPサーバーをTypeScriptで書く
- MCP Inspectorで動作を確かめる
- Claude Codeに登録して使う
- HTTPで公開してリモートMCPサーバーにする
手順1:MCPサーバーを作る準備をする

MCPサーバーを書く前に、開発の道具と、サーバーが返すデータを用意します。この記事のサーバーが返すのは、フォルダに置いたMarkdownの手順書です。準備することは、以下の3つです。
- Node.jsとTypeScriptのSDKを入れる
- 手順書は1つのフォルダに1本ずつ置く
- SKILL.mdの先頭にどんな依頼のときに使うかを書く
Node.jsとTypeScriptのSDKを入れる
MCPサーバーは、MCPのTypeScriptのSDKで書きます。SDKは、AIのアプリとのやりとりの決まりを代わりに引き受ける部品です。使ったのは、2026年10月30日の時点で最新の@modelcontextprotocol/serverの2.4.0です。パッケージの名前は、版1の@modelcontextprotocol/sdkから版2で変わりました。Node.jsは20以上が要ります。プロジェクトを作るコマンドは、以下のとおりです。
mkdir skill-mcp-server && cd skill-mcp-server
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node
package.jsonには、ESモジュールで動かすための"type": "module"と、ビルドのコマンドを足します。足す行は、以下のとおりです。
{
"type": "module",
"scripts": {
"build": "tsc"
}
}
TypeScriptの6.0からは@types/nodeが自動で読み込まれないため、"types": ["node"]を書きます。tsconfig.jsonの中身は、以下のとおりです。
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"types": ["node"],
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
手順書は1つのフォルダに1本ずつ置く
手順書ごとにフォルダを作り、本文をSKILL.mdという名前で置きます。例や表など、本文から読ませたいファイルは、同じフォルダの中に置きます。この記事の例のフォルダは、以下の形です。
skill-mcp-server/
├── skills/
│ ├── heading-check/
│ │ ├── SKILL.md
│ │ └── references/
│ │ └── examples.md
│ └── release-note/
│ └── SKILL.md
├── src/
├── package.json
└── tsconfig.json
フォルダの名前が、そのまま手順書の名前になります。利用者のAIは、手順書の名前をツールに渡して、読みたい手順書を指定します。
SKILL.mdの先頭にどんな依頼のときに使うかを書く
SKILL.mdの先頭には、---で囲んだ所に名前(name)と説明(description)を書きます。説明に書くのは、何をする手順書かと、どんな依頼のときに使うかです。list_skillsのツールは説明を一覧にして返すので、AIは説明を読んで手順書を選びます。見出しを点検する手順書のSKILL.mdは、以下のとおりです。
---
name: heading-check
description: 記事の見出し(## と ###)だけを読んで、何の話かわかるかを点検する。「見出しを点検して」「見出しを見て」と頼まれたときに使う
---
# 見出しの点検
1. 記事の `##` と `###` の行だけを抜き出す
2. 見出しを1本ずつ、本文を読まずに読み、何の話かわかるかを確かめる
3. わからない見出しがあったら、`references/examples.md` の直し方の例を読んでから、直した案を作る
4. 本文は書き換えない。今の見出し・直した案・理由の3列の表にして返す
本文の3番のように別のファイルを読ませる場面では、本文の中にファイルの場所を書いておきます。AIは書かれた場所をget_skill_fileのツールに渡して、例の表を読みに行きます。
手順2:ツールを持つMCPサーバーをTypeScriptで書く

準備ができたら、サーバーのコードを書きます。MCPサーバーのコードは、ツールの定義と、アプリとつなぐ入口の2つに分かれます。書く順番は、以下の2つです。
- 手順書を返す3つのツールを書く
- 標準入出力で起動する入口を書く
手順書を返す3つのツールを書く
3つのツールは、src/skills.tsにまとめます。registerToolに渡すのは、ツールの名前と説明と、受け取る値の形を書いたzodのスキーマです。ツールの説明はAIがツールを選ぶときに読む文なので、何を返すかに加えて、いつ使うかを書きます。
// 手順書(skills/<名前>/SKILL.md と同じフォルダのファイル)を返す3つのツール。
// stdio(src/index.ts)と HTTP(src/http.ts)の両方から使う
import { readdir, readFile } from "node:fs/promises";
import { join, resolve, sep } from "node:path";
import { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
// 配る手順書を置くフォルダ(build/ から見て ../skills)
const SKILLS_DIR = resolve(import.meta.dirname, "../skills");
async function skillNames(): Promise<string[]> {
const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
return entries.filter((e) => e.isDirectory()).map((e) => e.name);
}
// 手順書のフォルダの中だけを読む(「../」で外のファイルを読ませない)
async function readSkillFile(name: string, path: string): Promise<string> {
if (!(await skillNames()).includes(name)) {
throw new Error(`手順書「${name}」はありません。list_skills で名前を確かめてください`);
}
const base = join(SKILLS_DIR, name);
const file = resolve(base, path);
if (!file.startsWith(base + sep)) throw new Error("手順書のフォルダの外のファイルは読めません");
return readFile(file, "utf8");
}
// SKILL.md の先頭の --- で囲んだ所から description の行を取り出す
function descriptionOf(md: string): string {
const head = md.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
return head.match(/^description:\s*(.+)$/m)?.[1] ?? "";
}
const text = (t: string) => ({ content: [{ type: "text" as const, text: t }] });
// 呼ばれるたびに新しいサーバーを返す(SDK がつなぐ相手ごとに呼ぶ)
export function createServer() {
const server = new McpServer({ name: "lab-skills", version: "1.0.0" });
server.registerTool(
"list_skills",
{
description:
"配っている手順書の名前と、どんな依頼のときに使うかの一覧を返す。依頼に合う手順書があるかを、作業の前に確かめるときに使う",
inputSchema: z.object({}),
},
async () => {
const lines: string[] = [];
for (const name of await skillNames()) {
lines.push(`- ${name}: ${descriptionOf(await readSkillFile(name, "SKILL.md"))}`);
}
return text(lines.join("\n"));
},
);
server.registerTool(
"get_skill",
{
description: "手順書の本文(SKILL.md)を返す。list_skills で選んだ手順書で作業するときは、始める前に必ず読む",
inputSchema: z.object({ name: z.string().describe("list_skills に出た手順書の名前") }),
},
async ({ name }) => text(await readSkillFile(name, "SKILL.md")),
);
server.registerTool(
"get_skill_file",
{
description: "手順書の本文が読むように書いている、同じフォルダの別のファイル(例や表)を返す",
inputSchema: z.object({
name: z.string().describe("手順書の名前"),
path: z.string().describe("手順書のフォルダの中のパス(例: references/examples.md)"),
}),
},
async ({ name, path }) => text(await readSkillFile(name, path)),
);
return server;
}
手順書のファイルを読む関数には、フォルダの外に出ないための確かめを入れています。get_skill_fileに../../src/skills.tsのような場所を渡されると、手順書ではないファイルまで返してしまうからです。確かめに通らないときや無い名前を渡されたときは、関数が理由を書いたエラーを投げます。SDKはエラーの文を結果として呼んだ側に返すので、名前の間違いには、list_skillsで確かめ直すよう書いておきます。
標準入出力で起動する入口を書く
手元のClaude Codeから使うときは、Claude Codeがサーバーを起動し、標準入出力でやりとりします。入口のsrc/index.tsは、以下の9行です。
// 手元の Claude Code から使うときの入口(stdio)。
// 標準出力は MCP のやりとりに使うので、ログは console.error(標準エラー)に出す
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { createServer } from "./skills.js";
serveStdio(createServer, {
onerror: (error) => console.error("lab-skills の MCP サーバーでエラー:", error),
});
console.error("lab-skills の MCP サーバーを stdio で起動しました");
serveStdioは、2026年7月28日版の新しいつなぎ方と、2025年版の古いつなぎ方の両方に答えます。標準出力はやりとりに使うため、ログの出し先はconsole.errorの標準エラーです。標準出力に余計な文を書くと、やりとりのメッセージに混ざってサーバーが壊れる原因になります。npm run buildを実行すると、buildのフォルダにJavaScriptのファイルができます。
手順3:MCP Inspectorで動作を確かめる

Claude Codeにつなぐ前に、MCPの確かめ用の道具であるInspectorで、サーバーが答えるかを確かめます。InspectorのCLIは、画面を開かずにツールの一覧や結果を表示します。確かめることは、以下の2つです。
- ツールの一覧を新旧2つの版で出す
- 無い名前とフォルダの外の場所を渡す
ツールの一覧を新旧2つの版で出す
Inspectorは、何も指定しないと古いつなぎ方だけを試します。新しいアプリと古いアプリのどちらにも答えるかを見るため、--protocol-eraをmodernとlegacyに変えて2回実行します。
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era legacy --method tools/list
2026年10月30日に版2.13.0のInspectorで試すと、どちらの版でも3つのツールの名前と説明が返りました。list_skillsを呼ぶコマンドは、以下のとおりです。
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/call --tool-name list_skills
返った一覧には、2つの手順書の名前と説明が並びました。返った文は、以下のとおりです。
- heading-check: 記事の見出し(## と ###)だけを読んで、何の話かわかるかを点検する。「見出しを点検して」「見出しを見て」と頼まれたときに使う
- release-note: git の履歴から、利用者に向けた更新のお知らせを書く。「お知らせを書いて」「更新内容をまとめて」と頼まれたときに使う
無い名前とフォルダの外の場所を渡す
間違った値を渡したときに、サーバーが手順書のほかのファイルを返さないかも確かめます。試した2つの場合と結果は、以下のとおりです。
- get_skillに無い名前のnothingを渡すと、手順書が無いことと、list_skillsで名前を確かめるよう書いた文が返った
- get_skill_fileに
../../src/skills.tsを渡すと、フォルダの外のファイルは読めないと書いた文が返った
どちらの結果にも"isError": trueが付き、Inspectorはツールの失敗として表示しました。
手順4:Claude Codeに登録して使う

確かめたサーバーを、Claude Codeに登録して使います。登録から使うまでの手順は、以下の3つです。
- claude mcp addでフォルダごとに登録する
- サーバーのソースが無いフォルダで頼む
- サーバーの名前をClaude デスクトップアプリの中の名前と重ねない
claude mcp addでフォルダごとに登録する
登録には、claude mcp addのコマンドを使います。サーバーを使いたいフォルダに移り、--の後ろにサーバーを起動するコマンドを書くのが決まりです。
cd 使いたいフォルダ
claude mcp add lab-skills -- node /絶対パス/skill-mcp-server/build/index.js
スコープを指定しない登録は、登録したフォルダだけで使えるlocalのスコープになります。選べるスコープは、以下の表の3つです。
| スコープ | 使えるフォルダ | 書く場所 |
|---|---|---|
| local(指定しないとき) | 登録したフォルダだけ | 自分の~/.claude.json |
| project | 登録したフォルダだけ。チームと共有できる | フォルダの.mcp.json |
| user | 自分のすべてのフォルダ | 自分の~/.claude.json |
projectのスコープのサーバーは、使う前にClaude Codeが承認を求めます。登録できたかを確かめるコマンドは、claude mcp listです。Connectedと出れば、Claude Codeがサーバーを起動できています。
$ claude mcp list
lab-skills: node /…/skill-mcp-server/build/index.js - ✔ Connected
2026年10月30日に試すと、Claude デスクトップアプリのCodeのタブでも同じ登録が使えました。セッションの入力欄で/mcpと打つと、つながっているMCPサーバーが一覧で出ます。

サーバーのソースが無いフォルダで頼む
Claude Codeに頼むときは、サーバーのソースが無いフォルダを開きます。ソースのあるフォルダで頼むと、Claude Codeはツールを呼ばずに、手順書のファイルを直接読んでしまうことがあるからです。メリルでも2026年8月19日の試験で、サーバーを作ったリポジトリで起動したClaude Codeが、MCPを使わずにソースを読みました。空のフォルダから接続し直して、ツールを使う所まで確かめています。
この記事の撮影でも、サーバーがつながっていない間のClaude Codeは、設定に書いたパスをたどって手順書のファイルを直接読みました。撮り直しでは、点検してもらうdraft.mdだけを置いたフォルダを、Claude デスクトップアプリで開いています。

依頼の文には、手順書の名前もMCPも書いていません。Claude Codeはlist_skillsで手順書の一覧を読み、見出しを点検するheading-checkを選びました。

本文と例のファイルを読んだ後、Claude Codeは手順書の4番のとおり、今の見出し・直した案・理由の3列の表で答えました。手順書の「本文は書き換えない」も守り、draft.mdを書き換えるかを最後に尋ねています。

サーバーの名前をClaude デスクトップアプリの中の名前と重ねない
登録の名前には、Claude デスクトップアプリが中で使う名前と重ならないものを付けます。この記事のサーバーは、最初にskillsという名前で登録しました。ところが、Claude デスクトップアプリのCodeのタブでは、何度セッションを作り直してもツールが届きませんでした。
アプリがClaude Codeを起動するときに渡す「使わせないサーバーの名前」49個の中に、skillsが入っていたのが原因です。アプリの設定ファイル(claude_desktop_config.json)に同じ名前で登録したときは、以下のエラーが記録に残りました。
[skills] [error] Couldn't start for Cowork and Code sessions. Error: Its name collides with a reserved internal server name

名前をlab-skillsに変えて登録し直すと、ツールがセッションに届きました。どちらも2026年10月30日に、版4.4212.0のClaude デスクトップアプリで試した結果です。名前には、チームや会社の名前を付けた、ほかと重ならないものを選びましょう。
手順5:HTTPで公開してリモートMCPサーバーにする

標準入出力のサーバーは、同じPCのアプリからしか使えません。社外の人に配るときは、HTTPで待ち受けるサーバーにして、インターネットから届く場所に置きます。配る前にすることは、以下の3つです。
- HTTPの入口を足す
- 利用者ごとに止められる接続先を発行する
- 配る相手のアプリで1回ずつつないで確かめる
HTTPの入口を足す
SDKのcreateMcpHandlerは、HTTPの要求を受けてMCPの答えを返す部品を作ります。Node.jsで動かすときは、@modelcontextprotocol/nodeのtoNodeHandlerでつなぎます。手元で試すためのsrc/http.tsは、以下のとおりです。
// HTTP で待ち受ける入口(手元で試す用。127.0.0.1 の 3000 番だけで待つ)。
// 社外に配るときは、この前に「誰からの接続か」を確かめる仕組みを足す(handler は確かめない)
import { createServer as createHttpServer } from "node:http";
import { createMcpHandler } from "@modelcontextprotocol/server";
import { localhostHostValidation, localhostOriginValidation, toNodeHandler } from "@modelcontextprotocol/node";
import { createServer } from "./skills.js";
const handler = toNodeHandler(createMcpHandler(createServer));
const checkHost = localhostHostValidation();
const checkOrigin = localhostOriginValidation();
createHttpServer((req, res) => {
// ブラウザのページから手元のサーバーを呼ばせない(DNS rebinding の対策)
if (!checkHost(req, res) || !checkOrigin(req, res)) return;
if (new URL(req.url ?? "/", "http://127.0.0.1").pathname !== "/mcp") {
res.writeHead(404).end();
return;
}
void handler(req, res);
}).listen(3000, "127.0.0.1", () => {
console.error("lab-skills の MCP サーバーを http://127.0.0.1:3000/mcp で起動しました");
});
createMcpHandlerは、要求がどこから来たかを確かめません。手元で試す間は127.0.0.1だけで待ち受け、ブラウザのページから呼ばれないようにHostとOriginを確かめる部品を前に置きます。2026年10月30日に試した結果は、以下のとおりです。
- InspectorのCLIから新旧2つの版でlist_skillsを呼ぶと、どちらも一覧が返った
- 別のサイトのOriginを付けた要求は、403で断られた
/mcp以外の場所は404で、/mcpへのGETは405で断られた
利用者ごとに止められる接続先を発行する
社外に配るサーバーには、誰からの接続かを確かめる仕組みを前に足します。メリルのサーバーはCloudflare WorkersとD1で動かし、接続先を利用者ごとに発行する作りです。接続先を1件ずつ止められるので、解約や返金のときも、その人の分だけを止められます。
2026年10月8日には、テストで渡していた接続先14件をまとめて止めました。止めた後に有効だったのは、新しく発行した1件だけです。
配る相手のアプリで1回ずつつないで確かめる
Claude デスクトップアプリの利用者は、設定のコネクタの画面の「カスタムコネクタを追加」から、名前とHTTPSのURLを入れて登録します。

メリルのサーバーは、Claude Codeからはつながったのに、Claude デスクトップアプリからはつながりませんでした。原因は、アプリが送るMCP-Protocol-Versionのヘッダーを、自前で書いたサーバーが400で断っていたことです。2026年8月21日に断る処理を外し、同じ日にアプリからの接続が通ることを確かめました。
SDKを使うと、つなぎ方の版の取り決めはSDKが引き受けます。ただし、配る相手が使うアプリの数だけ、実際に1回ずつつないで確かめましょう。
MCPサーバーの作り方は準備から登録までの5つの手順で進める

MCPサーバーは、SDKを使えば、ツールの定義と入口だけの短いコードで作れます。手順書を配るサーバーを作った手順は、以下の5つです。
- SDKを入れ、手順書を1つのフォルダに1本ずつ置き、SKILL.mdの先頭にいつ使うかを書く
- 3つのツールを、いつ使うかを書いた説明と一緒にSDKで書く
- Inspectorで新旧2つのつなぎ方と、間違った値を渡したときを確かめる
- ソースの無いフォルダから、ほかと重ならない名前で登録して使う
- 社外に配るときはHTTPで公開し、利用者ごとに止められる接続先を発行する
手順書を直すだけで全員の手順がそろえば、配り直しの手間はなくなります。まずは自分の手順書を1本だけフォルダに置き、Claude Codeから読めるかを試しましょう。
つまずいた所
[skills] [error] Couldn't start for Cowork and Code sessions. Error: Its name collides with a reserved internal server name
MCPサーバーがClaude デスクトップアプリのCodeで使われないときの直し方
登録した名前のskillsが、アプリの中で使う名前とぶつかっていました。名前をlab-skillsに変えると、ツールがセッションに届きました。
この記事のもとにした記録と資料
- Build an MCP server(Model Context Protocol)(2026-10-30 確認。TypeScript の手順(@modelcontextprotocol/server と zod、Node.js 20 以上、"type": "module"、tsconfig.json)、標準出力にログを書かない注意、serveStdio が新旧2つのつなぎ方に答えること、Inspector の --protocol-era。2026-11-04 確認。サーバーが渡せる3種類(Resources・Tools・Prompts)、手順のある SDK の言語(Python・TypeScript・Java・Kotlin・C#・Ruby・Rust・Go))
- @modelcontextprotocol/server(npm)(2026-10-30 確認。版 2.4.0。版2が版1の @modelcontextprotocol/sdk に代わること、TypeScript 6.0 以上で "types": ["node"] が要ること)
- Serving over HTTP(MCP TypeScript SDK)(2026-10-30 確認。createMcpHandler、@modelcontextprotocol/node の toNodeHandler、handler が Host と Origin を確かめないこと)
- MCP 経由で Claude Code をツールに接続する(Claude Code Docs)(2026-10-30 確認。claude mcp add の書き方、local・project・user の3つのスコープと書く場所、project スコープの承認、claude mcp list)
- 株式会社メリルの作業記録「スキル配布のMCPサーバーの設計書」(2026-08-11。zip ではなく接続先の登録で配る目的、3つのツール、利用者ごとに止める考え方)
- 株式会社メリルの作業記録「MCPサーバーの構築のタスク」(2026-08-19 に試験が通り、08-20 に開通。08-21 に Claude デスクトップアプリから接続できない原因を直した記録。ソースのあるリポジトリでは MCP を使わずソースを読んだ記録)
- 株式会社メリルの作業記録「接続先の発行と無効化」(2026-10-08。配っている手順書4つ、テストで渡していた接続先14件を止めた記録)
- 自社の記録の集計(このサイトの scripts/data/mcp-server.py で2026-10-30に数えた)(zip の版3つと15日間、設計から開通までの9日、手順書4つ、止めた接続先14件)
- この記事のサーバーのコード(このサイトの samples/skill-mcp-server)(2026-10-30 に Inspector 2.13.0 と Claude デスクトップアプリ 4.4212.0 で試した)
Touch AI の録画講座
Claude Codeを活用した記事執筆自動化とセキュリティ対策
リサーチから構成・執筆・WordPressへの下書き保存まで。記事制作を自動化する仕組みを実演で学びます。
- 記事制作を自動化する仕組みを実演で学べる
- GitHub・Claude Codeの環境づくり
- 記事執筆の自動化とAPIキーの保護