0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

自作MCPサーバーで社内APIをClaude Codeに繋ぐ実践ガイド — 手作業を1日45分削減した

0
Last updated at Posted at 2026-07-12

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つです。

  1. description に「使用例」と「注意事項」を書く — モデルにはツール名・description・入力スキーマ(各フィールドの型や制約、.describe() の説明文)がまとめて提示され、どれもツール選択や引数生成に影響します。中でもdescriptionは自由記述で意図を伝えやすいので、ツール名だけに頼らず丁寧に書く価値があります
  2. zod でバリデーションする — 不正な引数はAPIに到達する前に弾く。エラーメッセージもAIへのフィードバックになります
  3. エラーは 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化しますか? ぜひコメントで教えてください。

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?