MCPツールがタイムアウトする原因｜再試行・キャンセル・冪等性の設計

send_email
create_order
charge_payment
delete_file
publish_post

クライアントが結果を受け取れなかった

サーバー側で処理されなかった

MCP Client
↓
tools/call
↓
MCP Server
↓
Tool実行
↓
CallToolResult
↓
MCP Client

Client
↓
tools/call
↓
Server
↓
外部APIを実行
↓
まだ処理中
↓
Client側のtimeout

{
  "resultType": "complete",
  "content": [
    {
      "type": "text",
      "text": "外部APIが503を返しました"
    }
  ],
  "isError": true
}

MCP Client
↓
MCP Server
↓
GitHub API
↓
GitHub側が遅い

外部HTTP API
データベース
ブラウザ自動操作
Shell Command
巨大ファイル処理
AI API

ブラウザ・ホスト
↓
MCP Client timeout
↓
HTTP Proxy timeout
↓
MCP Server
↓
外部API timeout
↓
外部サービス

const result =
  await client.callTool(
    {
      name: "search_documents",
      arguments: {
        query:
          "MCP cancellation",
      },
    },
    {
      timeout: 30_000,
    },
  );

timeout: 300_000

const result =
  await client.callTool(
    {
      name:
        "export_orders",

      arguments: {
        format: "csv",
      },
    },
    {
      timeout: 30_000,

      onprogress:
        (progress) => {
          console.log({
            progress:
              progress.progress,

            total:
              progress.total,

            message:
              progress.message,
          });
        },
    },
  );

resetTimeoutOnProgress: true

const result =
  await client.callTool(
    {
      name:
        "export_orders",

      arguments: {
        format: "csv",
      },
    },
    {
      timeout: 30_000,

      onprogress:
        (progress) => {
          console.log(
            progress,
          );
        },

      resetTimeoutOnProgress:
        true,

      maxTotalTimeout:
        300_000,
    },
  );

progress: 1
progress: 1
progress: 1
progress: 1

processed 100 / 1000
processed 200 / 1000
processed 300 / 1000

import {
  McpServer,
} from "@modelcontextprotocol/server";

import { z } from "zod";

const server =
  new McpServer({
    name:
      "file-processor",

    version:
      "1.0.0",
  });

server.registerTool(
  "process_files",
  {
    description:
      "ファイルを順番に処理します",

    inputSchema:
      z.object({
        files:
          z.array(
            z.string(),
          ),
      }),
  },
  async (
    { files },
    ctx,
  ) => {
    const progressToken =
      ctx.mcpReq._meta
        ?.progressToken;

    for (
      let index = 0;
      index <
      files.length;
      index += 1
    ) {
      await processFile(
        files[index],
      );

      if (
        progressToken !==
        undefined
      ) {
        await ctx.mcpReq.notify({
          method:
            "notifications/progress",

          params: {
            progressToken,

            progress:
              index + 1,

            total:
              files.length,

            message:
              `${files[index]}を処理しました`,
          },
        });
      }
    }

    return {
      content: [
        {
          type: "text",
          text:
            `${files.length}件を処理しました`,
        },
      ],
    };
  },
);

const controller =
  new AbortController();

const promise =
  client.callTool(
    {
      name:
        "scan_archive",

      arguments: {
        pages: 10_000,
      },
    },
    {
      signal:
        controller.signal,

      timeout:
        60_000,
    },
  );

setTimeout(() => {
  controller.abort(
    "ユーザーが停止しました",
  );
}, 5_000);

await promise;

server.registerTool(
  "scan_archive",
  {
    description:
      "アーカイブを解析します",

    inputSchema:
      z.object({
        pages:
          z.number()
            .int()
            .positive(),
      }),
  },
  async (
    { pages },
    ctx,
  ) => {
    let scanned = 0;

    for (
      let page = 0;
      page < pages;
      page += 1
    ) {
      if (
        ctx.mcpReq.signal
          .aborted
      ) {
        console.error(
          "Tool was cancelled",
          ctx.mcpReq.signal
            .reason,
        );

        break;
      }

      await scanPage(page);

      scanned += 1;
    }

    return {
      content: [
        {
          type: "text",
          text:
            `${scanned}ページ処理しました`,
        },
      ],
    };
  },
);

const response =
  await fetch(
    apiUrl,
    {
      signal:
        ctx.mcpReq.signal,
    },
  );

server.registerTool(
  "get_external_data",
  {
    description:
      "外部APIからデータを取得します",

    inputSchema:
      z.object({
        id:
          z.string(),
      }),
  },
  async (
    { id },
    ctx,
  ) => {
    const url =
      createApiUrl(id);

    const response =
      await fetch(
        url,
        {
          signal:
            ctx.mcpReq.signal,
        },
      );

    if (!response.ok) {
      return {
        content: [
          {
            type: "text",
            text:
              `API Error: ${response.status}`,
          },
        ],

        isError:
          true,
      };
    }

    return {
      content: [
        {
          type: "text",
          text:
            await response.text(),
        },
      ],
    };
  },
);

for (
  const row of rows
) {
  if (
    signal.aborted
  ) {
    throw new Error(
      "cancelled",
    );
  }

  await processRow(
    row,
  );
}

send_email開始
↓
SMTP Serverへ送信成功
↓
MCP ClientがTimeout
↓
Cancellation

timeout = 処理失敗

timeout = 最終結果を確認できなかった

search_documents

create_order

Client
↓
create_order
↓
Server
↓
注文作成成功
↓
Response送信直前に接続切断

注文1作成
+
注文2作成

get_user

create_order

{
  "name": "create_order",
  "arguments": {
    "operationId": "04b40a44-1716-4c5c-9652-7e8ee3440ae8",
    "productId": "product-123",
    "quantity": 1
  }
}

JSON-RPC request id

業務上のoperationId

server.registerTool(
  "create_order",
  {
    description:
      "注文を作成します",

    inputSchema:
      z.object({
        operationId:
          z.string()
            .uuid(),

        productId:
          z.string(),

        quantity:
          z.number()
            .int()
            .positive(),
      }),
  },
  async (
    {
      operationId,
      productId,
      quantity,
    },
    ctx,
  ) => {
    const existing =
      await db.orderOperation
        .findUnique({
          where: {
            operationId,
          },
        });

    if (existing) {
      return {
        content: [
          {
            type: "text",
            text:
              `既存の注文 ${existing.orderId} を返しました`,
          },
        ],

        structuredContent: {
          orderId:
            existing.orderId,

          duplicated:
            true,
        },
      };
    }

    if (
      ctx.mcpReq.signal
        .aborted
    ) {
      throw new Error(
        "cancelled",
      );
    }

    const order =
      await createOrder({
        productId,
        quantity,
      });

    await db.orderOperation
      .create({
        data: {
          operationId,
          orderId:
            order.id,
        },
      });

    return {
      content: [
        {
          type: "text",
          text:
            `注文 ${order.id} を作成しました`,
        },
      ],

      structuredContent: {
        orderId:
          order.id,

        duplicated:
          false,
      },
    };
  },
);

SELECT
↓
存在しない
↓
INSERT

CREATE TABLE
mcp_tool_operations (
  operation_id UUID
    PRIMARY KEY,

  tool_name VARCHAR(100)
    NOT NULL,

  status VARCHAR(32)
    NOT NULL,

  result JSONB,

  created_at
    TIMESTAMPTZ
    NOT NULL
    DEFAULT NOW(),

  updated_at
    TIMESTAMPTZ
    NOT NULL
    DEFAULT NOW()
);

await paymentApi.charge({
  amount,
  currency:
    "JPY",

  idempotencyKey:
    operationId,
});

MCP Client Retry
↓
MCP Server Retry
↓
Payment API Retry

pending
executing
completed
failed
unknown

成功したのか
失敗したのか

status = unknown

type OperationStatus =
  | "pending"
  | "executing"
  | "completed"
  | "failed"
  | "unknown";

completed

failed

type RetryPolicy =
  | "safe"
  | "idempotent_only"
  | "never";

type ToolPolicy = {
  retry:
    RetryPolicy;

  maxAttempts:
    number;
};

const policies:
  Record<
    string,
    ToolPolicy
  > = {
  search_documents: {
    retry: "safe",
    maxAttempts: 2,
  },

  get_weather: {
    retry: "safe",
    maxAttempts: 2,
  },

  create_order: {
    retry:
      "idempotent_only",
    maxAttempts: 2,
  },

  send_email: {
    retry:
      "idempotent_only",
    maxAttempts: 2,
  },

  delete_file: {
    retry: "never",
    maxAttempts: 1,
  },
};

Unknown tool: send_emali

503 Service Unavailable

customer_id does not exist

return {
  content: [
    {
      type: "text",
      text:
        "External API is temporarily unavailable",
    },
  ],

  structuredContent: {
    ok: false,
    code:
      "UPSTREAM_UNAVAILABLE",
    retryable:
      true,
  },

  isError:
    true,
};

return {
  content: [
    {
      type: "text",
      text:
        "customer_idが存在しません",
    },
  ],

  structuredContent: {
    ok: false,
    code:
      "CUSTOMER_NOT_FOUND",
    retryable:
      false,
  },

  isError:
    true,
};

timeoutしたか

Toolは読み取り専用か

副作用があるか

冪等化されているか

operationIdがあるか

外部APIも冪等か

function sleep(
  ms: number,
): Promise<void> {
  return new Promise(
    (resolve) => {
      setTimeout(
        resolve,
        ms,
      );
    },
  );
}

function getBackoff(
  attempt: number,
): number {
  const base =
    Math.min(
      8_000,
      500 *
        2 ** attempt,
    );

  const jitter =
    Math.floor(
      Math.random() *
        300,
    );

  return (
    base +
    jitter
  );
}

type CallToolInput = {
  name: string;

  arguments:
    Record<
      string,
      unknown
    >;
};

async function callToolWithRetry(
  input:
    CallToolInput,
) {
  const policy =
    policies[input.name] ?? {
      retry: "never",
      maxAttempts: 1,
    };

  let lastError:
    unknown;

  for (
    let attempt = 0;
    attempt <
    policy.maxAttempts;
    attempt += 1
  ) {
    try {
      const result =
        await client.callTool(
          input,
          {
            timeout:
              30_000,
          },
        );

      if (
        !result.isError
      ) {
        return result;
      }

      if (
        !isRetryableToolResult(
          result,
        )
      ) {
        return result;
      }

      if (
        policy.retry ===
          "never"
      ) {
        return result;
      }

      lastError =
        result;
    } catch (error) {
      lastError =
        error;

      if (
        !isRetryableMcpError(
          error
        )
      ) {
        throw error;
      }

      if (
        policy.retry ===
          "never"
      ) {
        throw error;
      }
    }

    if (
      attempt <
      policy.maxAttempts - 1
    ) {
      await sleep(
        getBackoff(
          attempt,
        ),
      );
    }
  }

  throw lastError;
}

import {
  SdkError,
  SdkErrorCode,
} from "@modelcontextprotocol/client";

function isRetryableMcpError(
  error: unknown,
): boolean {
  if (
    error instanceof
      SdkError
  ) {
    return (
      error.code ===
        SdkErrorCode
          .RequestTimeout ||
      error.code ===
        SdkErrorCode
          .ConnectionClosed
    );
  }

  return false;
}

停止

キャンセルされた
↓
一時エラーと判断
↓
自動Retry

const controller =
  new AbortController();

try {
  await client.callTool(
    request,
    {
      signal:
        controller.signal,
    },
  );
} catch (error) {
  if (
    controller.signal
      .aborted
  ) {
    throw new Error(
      "user_cancelled",
    );
  }

  throw error;
}

timeout

signal

return {
  content: [
    {
      type: "text",
      text:
        "Cancelled",
    },
  ],
};

再試行できる

安全に再試行できる

timeout: 3_600_000

tools/call
↓
Task Handle
↓
HTTP接続終了

数秒後

tasks/get
↓
working

数秒後

tasks/get
↓
completed

処理時間 = HTTP Requestを保持する時間

処理時間 ≠ HTTP Request保持時間

前のRequestで注文処理を始めたはず

operationId
jobId
basketId
taskId
transactionId

timeout: 30_000

const timeoutByTool:
  Record<
    string,
    number
  > = {
  get_user:
    5_000,

  search_documents:
    15_000,

  fetch_web_page:
    30_000,

  export_orders:
    60_000,
};

Agent max duration: 60秒

MCP Tool timeout: 300秒

Agent全体: 120秒

1 Tool: 最大30秒

MCP外部API: 最大20秒

type McpToolLog = {
  traceId: string;

  toolName: string;

  durationMs: number;

  status:
    | "completed"
    | "tool_error"
    | "timeout"
    | "cancelled"
    | "protocol_error";

  retryCount:
    number;

  operationId:
    string | null;
};

const startedAt =
  performance.now();

const apiStartedAt =
  performance.now();

const apiResult =
  await callExternalApi();

const apiDurationMs =
  performance.now() -
  apiStartedAt;

const durationMs =
  performance.now() -
  startedAt;

MCP Tool自体が遅い

DBが遅い

外部APIが遅い

Networkが遅い

duration_ms
timeout
retry_count
tool_name

SELECT
  tool_name,

  COUNT(*)
    AS calls,

  AVG(duration_ms)
    AS average_ms,

  PERCENTILE_CONT(0.95)
    WITHIN GROUP (
      ORDER BY duration_ms
    )
    AS p95_ms,

  COUNT(*) FILTER (
    WHERE
      status = 'timeout'
  )::NUMERIC
  /
  NULLIF(
    COUNT(*),
    0
  )
    AS timeout_rate

FROM mcp_tool_logs

WHERE
  created_at >=
    NOW()
    - INTERVAL '7 days'

GROUP BY
  tool_name;

SELECT
  tool_name,

  AVG(retry_count)
    AS average_retries,

  MAX(retry_count)
    AS max_retries

FROM mcp_tool_logs

WHERE
  created_at >=
    NOW()
    - INTERVAL '7 days'

GROUP BY
  tool_name;

Tool timed out.
Try again.

retryable

attempt

maxAttempts

operationId

{
  "ok": false,
  "code": "TIMEOUT",
  "retryable": true,
  "attempt": 1,
  "maxAttempts": 2
}

{
  "ok": false,
  "code": "TIMEOUT",
  "retryable": false,
  "attempt": 2,
  "maxAttempts": 2
}

もう一度送信しますか？

operationId検索 → completed →「すでに送信済み」

operationId検索 → failed → 再送可能

operationId検索 → unknown → 状態確認または人間判断

create_order

get_order_by_operation_id

create_order
↓
timeout
↓
get_order_by_operation_id
↓
注文あり
↓
Retryしない

create_export → export_id

get_export_status → processing

get_export_status → completed

download_export

なぜToolが終わらなかったのか

Clientは何秒待っているのか

Server内部の外部APIは何秒待つのか

Progressは返っているのか

Cancellationが下流まで伝わるのか

Retryしても安全なToolなのか

Toolが失敗した

結果を確認できなかった

Timeout
↓
Cancellation
↓
状態確認
↓
Retry可否判定
↓
必要なら同じoperationIdでRetry