Claude Codeに「顧客ID 12345の情報を取ってきて」と話しかけるだけで、社内のREST APIが叩かれてレスポンスが返ってくる。そんな状態を作るのに必要なのは、100行程度のTypeScriptと30分の作業でした。
私は個人で運用しているAIエージェント環境に自作MCPサーバーを組み込み、Slack通知・カレンダー参照・社内API呼び出しの手動コピペを1日あたり約45分削減しました。この記事では、その実装手順と、実際にハマった落とし穴をまとめます。
MCPの解説記事は増えてきましたが、「既存のMCPサーバーを入れてみた」で止まっているものが多く、自分の業務ツールを繋ぐ側の情報が不足していると感じています。本記事はそこを埋めることを狙っています。
前提条件
| 項目 | 本記事の環境 |
|---|---|
| クライアント | Claude Code(Claude Desktop でもほぼ同じ) |
| ランタイム | Node.js 20 以上 |
| SDK |
@modelcontextprotocol/sdk(TypeScript) |
| トランスポート | stdio(ローカル実行) |
| 対象 | 社内REST API / Slack / Googleカレンダー |
MCP(Model Context Protocol)は、AIクライアントに「ツール」を追加するための共通規格です。ざっくり言えば AIの手足を増やすための差込口 で、一度サーバーを書けばClaude CodeでもClaude Desktopでも同じものが使い回せます。
そもそも「自作」すべきか — 判断フロー
技術選定でいきなり手を動かすと後悔します。以前フレームワーク選定で候補が5つ並んだとき、要件(SSR必須・チーム3人・学習コスト重視)をClaude Codeに渡して比較表を作らせたところ、30分で合意形成まで到達しました。情報収集と整理はAIに任せ、最終判断は人間がやる。この分業はMCPの要否判断にもそのまま使えます。
判断基準を表にするとこうなります。
| 状況 | 推奨 |
|---|---|
| 公式/コミュニティのMCPサーバーが既にある(GitHub, Slack, AWS等) | 既存を使う。自作しない |
| 社内API・独自DB・レガシーシステムを繋ぎたい | 自作する |
| 1回きりの単発作業 | Bashスクリプトで十分。MCP化は不要 |
| 週3回以上、同じAPIを叩く | 自作する(回収が速い) |
| 認証が複雑(OAuth・SAML) | 自作するが、トークン管理を先に設計する |
私の実感として、初期の定義コストは1ツールあたり30分程度。週3回以上使うAPIなら1日で元が取れます。
ステップ1: 最小構成のMCPサーバーを立てる
まずは疎通確認用に、引数をそのまま返すだけのツールを作ります。
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init
npx tsc --init が生成する tsconfig.json はデフォルトのままだと outDir が未設定で、コンパイル後のJSがソースと同じ場所に散らばります。rootDir / outDir を明示し、SDKが内部で使う .js 拡張子つきimportを解決できるモジュール設定にしておきます。
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"rootDir": "./src",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src/**/*"]
}
package.json に "type": "module" を追加し、src/index.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-internal-tools",
version: "1.0.0",
});
server.registerTool(
"ping",
{
title: "疎通確認",
description: "MCPサーバーが正しく接続されているか確認する。動作テスト専用。",
inputSchema: { message: z.string().describe("エコーバックしたい文字列") },
},
async ({ message }) => ({
content: [{ type: "text", text: `pong: ${message}` }],
})
);
const transport = new StdioServerTransport();
await server.connect(transport);
ビルドしてClaude Codeに登録します。
npx tsc
claude mcp add my-tools -- node /absolute/path/to/my-mcp-server/dist/index.js
claude mcp list で my-tools: connected と出れば成功です。Claude Codeで「pingツールでhelloと送って」と話しかけて pong: hello が返れば、土台は完成です。
stdio トランスポートでは 標準出力がプロトコルの通信路 です。console.log() でデバッグ出力を書くと標準出力に本来のJSON-RPCメッセージ以外の文字列が混ざり、クライアント側のパースエラーや接続断の原因になります。ログは必ず console.error()(標準エラー)に出してください。私はこれで最初の1時間を溶かしました。
ステップ2: 社内APIをツールとしてラップする
ここからが本番です。以前、Claude Codeから社内のREST APIを叩くのに毎回curlコマンドを手入力しており、パラメータのミスも頻発していました。これをMCPツール化したところ、自然言語で指示するだけでAPI呼び出しが完了するようになり、手動操作比で80%の時間削減になりました。
server.registerTool(
"get_customer",
{
title: "顧客情報を取得",
description:
"顧客IDを指定して顧客のプロフィール・契約状況を取得する。" +
"顧客IDが不明な場合は search_customer を先に使うこと。" +
"例: get_customer({ customerId: '12345' })",
inputSchema: {
customerId: z
.string()
.regex(/^\d{5}$/, "顧客IDは5桁の数字")
.describe("顧客ID(5桁の数字。例: 12345)"),
includeContracts: z
.boolean()
.default(false)
.describe("契約履歴を含めるか。デフォルトはfalse(レスポンスが大きくなるため)"),
},
},
async ({ customerId, includeContracts }) => {
const res = await fetch(
`${process.env.INTERNAL_API_BASE}/customers/${customerId}?contracts=${includeContracts}`,
{ headers: { Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}` } }
);
if (!res.ok) {
return {
isError: true,
content: [{ type: "text", text: `APIエラー ${res.status}: ${await res.text()}` }],
};
}
const data = await res.json();
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
}
);
ポイントは3つです。
-
description に「使用例」と「注意事項」を書く — モデルにはツール名・description・入力スキーマ(各フィールドの型や制約、
.describe()の説明文)がまとめて提示され、どれもツール選択や引数生成に影響します。中でもdescriptionは自由記述で意図を伝えやすいので、ツール名だけに頼らず丁寧に書く価値があります - zod でバリデーションする — 不正な引数はAPIに到達する前に弾く。エラーメッセージもAIへのフィードバックになります
-
エラーは throw せず
isError: trueで返す —isError: trueを使うと「ツール実行は失敗した」という結果をモデルが読める形で明示でき、内容を見て自己修正しやすくなります。throwした場合の変換・表示のされ方はSDKやクライアント実装に依存するため、挙動を制御したいならisErrorで返す方が確実です
Slackやカレンダーも同じ形でツール化しました。Slack通知・Googleカレンダー参照・GitHub操作・ファイルシステムアクセスをまとめて登録した結果、手動でコピペしていた連携作業が1日あたり約45分なくなりました。ツール定義のスキーマ設計が精度を左右するので、入力パラメータの説明文は面倒でも丁寧に書く価値があります。
ステップ3: 障害耐性を組み込む
これは見落としがちですが、実運用で最も効いた部分です。
エージェントが外部APIを呼ぶ際、タイムアウトやレートリミットで処理が止まることがありました。しかも人間が気づくまで放置されるケースもあり、朝になってジョブが半日止まっていた、ということが起きます。
対策として、ツール実行部分に指数バックオフ付きリトライを入れ、リトライも尽きて失敗したら呼び出し側でcatchし、承認キューに「手動対応依頼」として通知する仕組みにしました(fetchWithRetry 自体は通知を行わず、最終失敗時に例外を投げるだけです。通知は下記のように呼び出し側で行っています)。結果、一時的なAPI障害による処理停止はゼロになりました。
async function fetchWithRetry(url: string, init: RequestInit, maxAttempts = 3) {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const res = await fetch(url, { ...init, signal: AbortSignal.timeout(10_000) });
// 5xx とレートリミットはリトライ対象、4xx は即座に諦める
if (res.status < 500 && res.status !== 429) return res;
if (attempt === maxAttempts - 1) return res;
} catch (e) {
console.error(`[retry ${attempt + 1}/${maxAttempts}]`, e);
if (attempt === maxAttempts - 1) throw e;
}
// 最終試行(attempt === maxAttempts - 1)はここに到達せず即return/throwするため、
// 実際に発生する待機は 1s, 2s の2回のみ(4sの待機は起きない)
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
}
throw new Error("unreachable");
}
// 呼び出し側:最終的な失敗をキャッチして承認キューに通知する
try {
const res = await fetchWithRetry(url, init);
// ...res を使った処理
} catch (e) {
await notifyApprovalQueue({ type: "manual_action_required", error: String(e) });
}
4xxはリトライしないのが重要です。認証エラーやバリデーションエラーを繰り返しても結果は変わらず、待ち時間が増えるだけです。
ハマりどころ早見表
実際に踏んだ地雷を一覧にしておきます。
| 症状 | 原因 | 対処 |
|---|---|---|
connected にならない |
stdout にログを出している |
console.error() に変更 |
| サーバーが即終了する | 相対パスで登録し、実行時のカレントディレクトリから解決できなかった |
claude mcp add に絶対パスを渡す |
| AIがツールを呼んでくれない | description が薄い | 使用例・使うべき場面を description に追記 |
| 引数が毎回間違う | パラメータの説明不足 |
.describe() に例と形式を明記 |
| 環境変数が読めない | Claude Codeを起動したプロセスにその変数が存在しない(GUI起動やログインシェル未経由など) | まず起動元プロセスに変数があるか確認。確実に渡したい場合は claude mcp add -e KEY=value で明示的に設定する |
| レスポンスが長すぎてコンテキストを食う | JSON をそのまま返している | 必要フィールドだけ抽出して返す |
| 意図しない書き込みが走った | 破壊的操作をツール化した | 書き込み系は承認フローを挟む(後述) |
最後の1行は特に重要です。読み取り系ツールは自由に呼ばせて構いませんが、削除・送信・デプロイのような外部影響のある操作は、MCPツールから直接実行させない方が安全です。私は「ドラフト生成 → 承認キューに格納 → 人間が承認 → 実行」の4ステップにしています。
精度を上げるコツ: いきなり呼ばせない
複雑なタスクをMCPツール経由でこなさせると、要件の一部が抜け落ちることがあります。これはコード生成でも同じで、複雑なビジネスロジックの実装依頼が「条件分岐の一部を無視した実装」になって返ってくることがありました。
そこで、実装や実行の前に「まず要件を箇条書きで整理し、各要件の方針を説明してから着手して」というステップを踏ませたところ、手戻りが80%減りました。
MCPでも同じで、CLAUDE.md にこう書いておくだけで暴発が減ります。
## MCPツール利用ルール
- 書き込み系ツール(send_*, delete_*, deploy_*)を呼ぶ前に、
実行内容を箇条書きで提示し、承認を得ること。
- 読み取り系ツールは確認不要。自由に呼んでよい。
- APIエラーが3回続いたら、リトライせず人間に報告すること。
「いきなり手を動かさせない」——人間のエンジニアと同じです。
まとめ
- 既存のMCPサーバーがあるなら自作しない。社内API・独自システムこそ自作の価値がある
- 私の実感では1ツールの実装コストは約30分。手動コピペしていた作業が数分→数秒になった分、週3回以上使うAPIなら体感的にはすぐ元が取れた
-
console.log()は禁止。stdout はプロトコルの通信路 - description と
.describe()はツール選択・引数生成の精度に大きく影響する体感があった。面倒でも丁寧に書く - リトライと通知を最初から入れる。障害耐性は後付けしづらい
- 書き込み系は承認フローを挟む
MCPは「AIの手足を増やす仕組み」です。手足が増えるほど便利になりますが、同時に手足が振り回されたときの被害範囲も広がる。この2つをセットで設計するのが、実運用に乗せるための分岐点だと思っています。
この記事が参考になったら、いいね・ストック していただけると励みになります。
Claude Code・AIエージェント・業務自動化の実装Tipsを継続的に発信しています。フォロー しておくと新着が届きます。
みなさんは、自作するとしたらどの業務ツールを最初にMCP化しますか? ぜひコメントで教えてください。