MCP（Model Context Protocol）：開発者のための完全ガイド

spinny:~/writing $ vim mcp-model-context-protocol-guide.md

1~
2**Model Context Protocol（MCP）** は、Anthropic が作成したオープンスタンダードで、AI モデルが外部ツール、データソース、サービスとどのように通信するかを定義します。これを「AI の USB-C」と考えてください  -  標準化されたインターフェースを通じて、任意の AI エージェントが任意のツールと通信できるユニバーサルコネクタです。
3~
4ローンチ以来、MCP は **月間9,700万回以上の SDK ダウンロード** を達成し、すべての主要 AI プロバイダーに採用されています：Anthropic、OpenAI、Google、Microsoft、Amazon。このガイドでは、MCP を使って構築するために知っておくべきすべてを探ります。
5~
6## MCP が存在する理由
7~
8MCP 以前は、すべての AI アプリケーションが使用したい各ツールに対してカスタム統合を構築する必要がありました。AI にファイルを読ませたい？カスタムコードを書く。データベースをクエリする？さらにカスタムコード。Slack に投稿する？また別の統合。
9~
10これにより **N×M 問題** が発生しました：N 個の AI アプリケーションがそれぞれ M 個のカスタム統合を必要とし、作業の重複と断片化したエコシステムにつながりました。
11~
12```mermaid
13graph TD
14    subgraph "Before MCP (N×M)"
15        A1[AI App 1] --> T1[GitHub Integration]
16        A1 --> T2[Slack Integration]
17        A1 --> T3[DB Integration]
18        A2[AI App 2] --> T4[GitHub Integration]
19        A2 --> T5[Slack Integration]
20        A2 --> T6[DB Integration]
21    end
22```
23~
24MCP はこれを、任意の AI クライアントが任意の MCP サーバーと通信するために使用できる**単一のプロトコル**で解決します：
25~
26```mermaid
27graph TD
28    subgraph "With MCP (N+M)"
29        A1[AI App 1] --> MCP[MCP Protocol]
30        A2[AI App 2] --> MCP
31        MCP --> S1[GitHub Server]
32        MCP --> S2[Slack Server]
33        MCP --> S3[DB Server]
34    end
35```
36~
37## 基本概念
38~
39MCP には3つの基本的なプリミティブがあります：
40~
41### 1. ツール（Tools）
42ツールは AI が呼び出せる関数です。「ファイルを作成する」「データベースをクエリする」「メッセージを送信する」などのアクションを表します。各ツールには名前、説明、パラメータの JSON Schema があります。
43~
44```typescript
45{
46  name: "create_issue",
47  description: "Create a new GitHub issue",
48  inputSchema: {
49    type: "object",
50    properties: {
51      title: { type: "string", description: "Issue title" },
52      body: { type: "string", description: "Issue body" },
53      repo: { type: "string", description: "Repository name" }
54    },
55    required: ["title", "repo"]
56  }
57}
58```
59~
60### 2. リソース（Resources）
61リソースは AI が読み取れるデータです。ファイル、データベースレコード、API レスポンス、その他のデータソースを表します。リソースは URI で識別されます。
62~
63```typescript
64{
65  uri: "file:///Users/dev/project/README.md",
66  name: "Project README",
67  mimeType: "text/markdown"
68}
69```
70~
71### 3. プロンプト（Prompts）
72プロンプトはインタラクションの構造化を助ける再利用可能なテンプレートです。動的パラメータを含めることができ、一般的なワークフローの標準化に役立ちます。
73~
74```typescript
75{
76  name: "code_review",
77  description: "Review code changes for quality and security",
78  arguments: [
79    { name: "diff", description: "The code diff to review", required: true }
80  ]
81}
82```
83~
84## アーキテクチャ
85~
86MCP はクライアント-サーバーアーキテクチャに従います：
87~
88```mermaid
89graph LR
90    subgraph "Host Application"
91        Client[MCP Client]
92    end
93~
94    subgraph "MCP Server"
95        Server[Server Process]
96        Server --> Tools[Tools]
97        Server --> Resources[Resources]
98        Server --> Prompts[Prompts]
99    end
100~
101    Client -- "JSON-RPC 2.0\n(stdio or SSE)" --> Server
102```
103~
104- **ホスト**：AI アプリケーション（Claude Desktop、Cursor、カスタムアプリ）
105- **クライアント**：MCP サーバーとの 1:1 接続を維持
106- **サーバー**：ツール、リソース、プロンプトをクライアントに公開
107- **トランスポート**：stdio（ローカル）または Server-Sent Events（リモート）上の JSON-RPC 2.0 で通信
108~
109## MCP サーバーの構築
110~
111JSON ファイルに保存されたタスクリストとやり取りする実用的な MCP サーバーを構築しましょう。
112~
113### セットアップ
114~
115```bash
116mkdir mcp-todo-server && cd mcp-todo-server
117npm init -y
118npm install @modelcontextprotocol/sdk zod
119```
120~
121### サーバーの実装
122~
123```typescript
124// src/index.ts
125import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
126import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
127import { z } from "zod";
128import fs from "fs";
129~
130const TODO_FILE = "./todos.json";
131~
132function readTodos(): { id: number; text: string; done: boolean }[] {
133  if (!fs.existsSync(TODO_FILE)) return [];
134  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
135}
136~
137function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
138  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
139}
140~
141const server = new McpServer({
142  name: "todo-server",
143  version: "1.0.0",
144});
145~
146// Tool: Add a todo
147server.tool(
148  "add_todo",
149  "Add a new todo item",
150  { text: z.string().describe("The todo text") },
151  async ({ text }) => {
152    const todos = readTodos();
153    const newTodo = { id: Date.now(), text, done: false };
154    todos.push(newTodo);
155    writeTodos(todos);
156    return { content: [{ type: "text", text: `Added: "${text}"` }] };
157  }
158);
159~
160// Tool: List todos
161server.tool(
162  "list_todos",
163  "List all todo items",
164  {},
165  async () => {
166    const todos = readTodos();
167    const list = todos
168      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
169      .join("\n");
170    return { content: [{ type: "text", text: list || "No todos yet." }] };
171  }
172);
173~
174// Tool: Complete a todo
175server.tool(
176  "complete_todo",
177  "Mark a todo as completed",
178  { id: z.number().describe("The todo ID to complete") },
179  async ({ id }) => {
180    const todos = readTodos();
181    const todo = todos.find((t) => t.id === id);
182    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
183    todo.done = true;
184    writeTodos(todos);
185    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
186  }
187);
188~
189// Resource: Current todos as a readable resource
190server.resource(
191  "todos://list",
192  "Current todo list",
193  async () => ({
194    contents: [{
195      uri: "todos://list",
196      mimeType: "application/json",
197      text: JSON.stringify(readTodos(), null, 2),
198    }],
199  })
200);
201~
202// Start the server
203const transport = new StdioServerTransport();
204await server.connect(transport);
205```
206~
207### 設定
208~
209このサーバーを Claude Desktop で使用するには、設定に追加してください：
210~
211```json
212{
213  "mcpServers": {
214    "todo": {
215      "command": "npx",
216      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
217    }
218  }
219}
220```
221~
222## MCP クライアントの構築
223~
224任意の MCP サーバーに接続するカスタムクライアントも構築できます：
225~
226```typescript
227import { Client } from "@modelcontextprotocol/sdk/client/index.js";
228import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
229~
230const transport = new StdioClientTransport({
231  command: "npx",
232  args: ["tsx", "./src/index.ts"],
233});
234~
235const client = new Client({ name: "my-client", version: "1.0.0" });
236await client.connect(transport);
237~
238// List available tools
239const { tools } = await client.listTools();
240console.log("Available tools:", tools.map((t) => t.name));
241~
242// Call a tool
243const result = await client.callTool({
244  name: "add_todo",
245  arguments: { text: "Write MCP blog post" },
246});
247console.log(result);
248```
249~
250## 人気の MCP サーバー
251~
252MCP エコシステムは急速に成長しています。最も人気のあるサーバーの一部を紹介します：
253~
254| サーバー | 説明 | ユースケース |
255|----------|------|-------------|
256| **GitHub** | Issue、PR の作成、リポジトリの管理 | 開発ワークフロー |
257| **Slack** | メッセージの送信、チャンネルの管理 | チームコミュニケーション |
258| **PostgreSQL** | データベースのクエリと管理 | データアクセス |
259| **Filesystem** | ファイルの読み取り、書き込み、検索 | ローカル開発 |
260| **Puppeteer** | ブラウザの自動化とスクレイピング | Web テスト |
261| **Sentry** | エラー監視とデバッグ | 本番サポート |
262| **Supabase** | データベース、認証、ストレージ | バックエンド操作 |
263~
264## MCP vs A2A（Agent-to-Agent）
265~
266MCP が**エージェント-ツール**間の通信を処理するのに対し、Google の **A2A（Agent-to-Agent）** プロトコルは**エージェント-エージェント**間の通信を処理します。これらは相補的です：
267~
268```mermaid
269graph TD
270    Agent1[Agent 1] -- "A2A Protocol" --> Agent2[Agent 2]
271    Agent1 -- "MCP Protocol" --> Tool1[GitHub MCP Server]
272    Agent2 -- "MCP Protocol" --> Tool2[Database MCP Server]
273```
274~
275- **MCP**：AI エージェントがツールを使用する方法（垂直統合）
276- **A2A**：AI エージェント同士が協力する方法（水平統合）
277~
278## ベストプラクティス
279~
2801. **サーバーを焦点を絞る**：ドメインごとに1つのサーバー（GitHub サーバー、Slack サーバーなど）。モノリシックなサーバーを構築しないでください。
2812. **Zod で入力を検証する**：常に適切なスキーマでツールの入力を検証してください。
2823. **エラーを適切に処理する**：スタックトレースではなく、意味のあるエラーメッセージを返してください。
2834. **読み取り専用データにはリソースを使用する**：AI がデータの読み取りのみが必要な場合は、ツールではなくリソースとして公開してください。
2845. **適切な説明を追加する**：ツールとパラメータの良い説明は、AI が各ツールをいつ、どのように使用するかを理解するのに役立ちます。
2856. **MCP Inspector でテストする**：`npx @modelcontextprotocol/inspector` を使用してサーバーを対話的にテストしてください。
286~
287## はじめに
288~
289```bash
290# Create a new MCP server from template
291npx @modelcontextprotocol/create-server my-server
292~
293# Test with the MCP Inspector
294npx @modelcontextprotocol/inspector npx tsx ./src/index.ts
295```
296~
297## まとめ
298~
299MCP は 2026 年に AI ツール利用のデファクトスタンダードとなりました。カスタム AI エージェントの構築、Claude Code の拡張、既存プラットフォームへの統合の作成のいずれであっても、MCP を理解することは不可欠です。このプロトコルは午後の数時間で学べるほどシンプルですが、本番レベルの AI ワークフローを構築するのに十分な強力さを持っています。
300~
301**次のステップ：**
302- [MCP 仕様](https://spec.modelcontextprotocol.io/)を探索する
303- [既存の MCP サーバー](https://github.com/modelcontextprotocol/servers)をブラウズしてインスピレーションを得る
304- TypeScript または Python SDK で最初のサーバーを構築する
305- Claude Desktop または MCP Inspector でテストする
306~

NORMAL · mcp-model-context-protocol-guide.md [readonly]306 lines · :q to close

2**Model Context Protocol（MCP）** は、Anthropic が作成したオープンスタンダードで、AI モデルが外部ツール、データソース、サービスとどのように通信するかを定義します。これを「AI の USB-C」と考えてください - 標準化されたインターフェースを通じて、任意の AI エージェントが任意のツールと通信できるユニバーサルコネクタです。

4ローンチ以来、MCP は **月間9,700万回以上の SDK ダウンロード** を達成し、すべての主要 AI プロバイダーに採用されています：Anthropic、OpenAI、Google、Microsoft、Amazon。このガイドでは、MCP を使って構築するために知っておくべきすべてを探ります。

6## MCP が存在する理由

8MCP 以前は、すべての AI アプリケーションが使用したい各ツールに対してカスタム統合を構築する必要がありました。AI にファイルを読ませたい？カスタムコードを書く。データベースをクエリする？さらにカスタムコード。Slack に投稿する？また別の統合。

10これにより **N×M 問題** が発生しました：N 個の AI アプリケーションがそれぞれ M 個のカスタム統合を必要とし、作業の重複と断片化したエコシステムにつながりました。

11~

12```mermaid

13graph TD

14 subgraph "Before MCP (N×M)"

15 A1[AI App 1] --> T1[GitHub Integration]

16 A1 --> T2[Slack Integration]

17 A1 --> T3[DB Integration]

18 A2[AI App 2] --> T4[GitHub Integration]

19 A2 --> T5[Slack Integration]

20 A2 --> T6[DB Integration]

21 end

22```

23~

24MCP はこれを、任意の AI クライアントが任意の MCP サーバーと通信するために使用できる**単一のプロトコル**で解決します：

25~

26```mermaid

27graph TD

28 subgraph "With MCP (N+M)"

29 A1[AI App 1] --> MCP[MCP Protocol]

30 A2[AI App 2] --> MCP

31 MCP --> S1[GitHub Server]

32 MCP --> S2[Slack Server]

33 MCP --> S3[DB Server]

34 end

35```

36~

37## 基本概念

38~

39MCP には3つの基本的なプリミティブがあります：

40~

41### 1. ツール（Tools）

42ツールは AI が呼び出せる関数です。「ファイルを作成する」「データベースをクエリする」「メッセージを送信する」などのアクションを表します。各ツールには名前、説明、パラメータの JSON Schema があります。

43~

44```typescript

45{

46 name: "create_issue",

47 description: "Create a new GitHub issue",

48 inputSchema: {

49 type: "object",

50 properties: {

51 title: { type: "string", description: "Issue title" },

52 body: { type: "string", description: "Issue body" },

53 repo: { type: "string", description: "Repository name" }

54 },

55 required: ["title", "repo"]

56 }

57}

58```

59~

60### 2. リソース（Resources）

61リソースは AI が読み取れるデータです。ファイル、データベースレコード、API レスポンス、その他のデータソースを表します。リソースは URI で識別されます。

62~

63```typescript

64{

65 uri: "file:///Users/dev/project/README.md",

66 name: "Project README",

67 mimeType: "text/markdown"

68}

69```

70~

71### 3. プロンプト（Prompts）

72プロンプトはインタラクションの構造化を助ける再利用可能なテンプレートです。動的パラメータを含めることができ、一般的なワークフローの標準化に役立ちます。

73~

74```typescript

75{

76 name: "code_review",

77 description: "Review code changes for quality and security",

78 arguments: [

79 { name: "diff", description: "The code diff to review", required: true }

80 ]

81}

82```

83~

84## アーキテクチャ

85~

86MCP はクライアント-サーバーアーキテクチャに従います：

87~

88```mermaid

89graph LR

90 subgraph "Host Application"

91 Client[MCP Client]

92 end

93~

94 subgraph "MCP Server"

95 Server[Server Process]

96 Server --> Tools[Tools]

97 Server --> Resources[Resources]

98 Server --> Prompts[Prompts]

99 end

100~

101 Client -- "JSON-RPC 2.0\n(stdio or SSE)" --> Server

102```

103~

104- **ホスト**：AI アプリケーション（Claude Desktop、Cursor、カスタムアプリ）

105- **クライアント**：MCP サーバーとの 1:1 接続を維持

106- **サーバー**：ツール、リソース、プロンプトをクライアントに公開

107- **トランスポート**：stdio（ローカル）または Server-Sent Events（リモート）上の JSON-RPC 2.0 で通信

108~

109## MCP サーバーの構築

110~

111JSON ファイルに保存されたタスクリストとやり取りする実用的な MCP サーバーを構築しましょう。

112~

113### セットアップ

114~

115```bash

116mkdir mcp-todo-server && cd mcp-todo-server

117npm init -y

118npm install @modelcontextprotocol/sdk zod

119```

120~

121### サーバーの実装

122~

123```typescript

124// src/index.ts

125import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

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

127import { z } from "zod";

128import fs from "fs";

129~

130const TODO_FILE = "./todos.json";

131~

132function readTodos(): { id: number; text: string; done: boolean }[] {

133 if (!fs.existsSync(TODO_FILE)) return [];

134 return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));

135}

136~

137function writeTodos(todos: { id: number; text: string; done: boolean }[]) {

138 fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));

139}

140~

141const server = new McpServer({

142 name: "todo-server",

143 version: "1.0.0",

144});

145~

146// Tool: Add a todo

147server.tool(

148 "add_todo",

149 "Add a new todo item",

150 { text: z.string().describe("The todo text") },

151 async ({ text }) => {

152 const todos = readTodos();

153 const newTodo = { id: Date.now(), text, done: false };

154 todos.push(newTodo);

155 writeTodos(todos);

156 return { content: [{ type: "text", text: `Added: "${text}"` }] };

157 }

158);

159~

160// Tool: List todos

161server.tool(

162 "list_todos",

163 "List all todo items",

164 {},

165 async () => {

166 const todos = readTodos();

167 const list = todos

168 .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)

169 .join("\n");

170 return { content: [{ type: "text", text: list || "No todos yet." }] };

171 }

172);

173~

174// Tool: Complete a todo

175server.tool(

176 "complete_todo",

177 "Mark a todo as completed",

178 { id: z.number().describe("The todo ID to complete") },

179 async ({ id }) => {

180 const todos = readTodos();

181 const todo = todos.find((t) => t.id === id);

182 if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };

183 todo.done = true;

184 writeTodos(todos);

185 return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };

186 }

187);

188~

189// Resource: Current todos as a readable resource

190server.resource(

191 "todos://list",

192 "Current todo list",

193 async () => ({

194 contents: [{

195 uri: "todos://list",

196 mimeType: "application/json",

197 text: JSON.stringify(readTodos(), null, 2),

198 }],

199 })

200);

201~

202// Start the server

203const transport = new StdioServerTransport();

204await server.connect(transport);

205```

206~

207### 設定

208~

209このサーバーを Claude Desktop で使用するには、設定に追加してください：

210~

211```json

212{

213 "mcpServers": {

214 "todo": {

215 "command": "npx",

216 "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]

217 }

218 }

219}

220```

221~

222## MCP クライアントの構築

223~

224任意の MCP サーバーに接続するカスタムクライアントも構築できます：

225~

226```typescript

227import { Client } from "@modelcontextprotocol/sdk/client/index.js";

228import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

229~

230const transport = new StdioClientTransport({

231 command: "npx",

232 args: ["tsx", "./src/index.ts"],

233});

234~

235const client = new Client({ name: "my-client", version: "1.0.0" });

236await client.connect(transport);

237~

238// List available tools

239const { tools } = await client.listTools();

240console.log("Available tools:", tools.map((t) => t.name));

241~

242// Call a tool

243const result = await client.callTool({

244 name: "add_todo",

245 arguments: { text: "Write MCP blog post" },

246});

247console.log(result);

248```

249~

250## 人気の MCP サーバー

251~

252MCP エコシステムは急速に成長しています。最も人気のあるサーバーの一部を紹介します：

253~

254| サーバー | 説明 | ユースケース |

255|----------|------|-------------|

256| **GitHub** | Issue、PR の作成、リポジトリの管理 | 開発ワークフロー |

257| **Slack** | メッセージの送信、チャンネルの管理 | チームコミュニケーション |

258| **PostgreSQL** | データベースのクエリと管理 | データアクセス |

259| **Filesystem** | ファイルの読み取り、書き込み、検索 | ローカル開発 |

260| **Puppeteer** | ブラウザの自動化とスクレイピング | Web テスト |

261| **Sentry** | エラー監視とデバッグ | 本番サポート |

262| **Supabase** | データベース、認証、ストレージ | バックエンド操作 |

263~

264## MCP vs A2A（Agent-to-Agent）

265~

266MCP が**エージェント-ツール**間の通信を処理するのに対し、Google の **A2A（Agent-to-Agent）** プロトコルは**エージェント-エージェント**間の通信を処理します。これらは相補的です：

267~

268```mermaid

269graph TD

270 Agent1[Agent 1] -- "A2A Protocol" --> Agent2[Agent 2]

271 Agent1 -- "MCP Protocol" --> Tool1[GitHub MCP Server]

272 Agent2 -- "MCP Protocol" --> Tool2[Database MCP Server]

273```

274~

275- **MCP**：AI エージェントがツールを使用する方法（垂直統合）

276- **A2A**：AI エージェント同士が協力する方法（水平統合）

277~

278## ベストプラクティス

279~

2801. **サーバーを焦点を絞る**：ドメインごとに1つのサーバー（GitHub サーバー、Slack サーバーなど）。モノリシックなサーバーを構築しないでください。

2812. **Zod で入力を検証する**：常に適切なスキーマでツールの入力を検証してください。

2823. **エラーを適切に処理する**：スタックトレースではなく、意味のあるエラーメッセージを返してください。

2834. **読み取り専用データにはリソースを使用する**：AI がデータの読み取りのみが必要な場合は、ツールではなくリソースとして公開してください。

2845. **適切な説明を追加する**：ツールとパラメータの良い説明は、AI が各ツールをいつ、どのように使用するかを理解するのに役立ちます。

2856. **MCP Inspector でテストする**：`npx @modelcontextprotocol/inspector` を使用してサーバーを対話的にテストしてください。

286~

287## はじめに

288~

289```bash

290# Create a new MCP server from template

291npx @modelcontextprotocol/create-server my-server

292~

293# Test with the MCP Inspector

294npx @modelcontextprotocol/inspector npx tsx ./src/index.ts

295```

296~

297## まとめ

298~

299MCP は 2026 年に AI ツール利用のデファクトスタンダードとなりました。カスタム AI エージェントの構築、Claude Code の拡張、既存プラットフォームへの統合の作成のいずれであっても、MCP を理解することは不可欠です。このプロトコルは午後の数時間で学べるほどシンプルですが、本番レベルの AI ワークフローを構築するのに十分な強力さを持っています。

300~

301**次のステップ：**

302- [MCP 仕様](https://spec.modelcontextprotocol.io/)を探索する

303- [既存の MCP サーバー](https://github.com/modelcontextprotocol/servers)をブラウズしてインスピレーションを得る

304- TypeScript または Python SDK で最初のサーバーを構築する

305- Claude Desktop または MCP Inspector でテストする

306~