musistudio/claude-code-router · error · Error

MCP request failed (${this.server.name}): ${String(response.

Error message

MCP request failed (${this.server.name}): ${String(response.error.message ?? "Unknown error")}

What it means

Thrown when a JSON-RPC request to an MCP server returns a response object containing an `error` field. The message embeds the server name and the error message returned by the remote MCP server (or "Unknown error" if the error object lacks a message). This is the library's wrapper for protocol-level MCP failures (tool call failures, invalid params, method not found) as opposed to transport failures.

Source

Thrown at packages/core/src/mcp/toolhub-mcp.ts:1175

    this.initialized = true;
  }

  private async notification(method: string, params: Record<string, unknown>): Promise<void> {
    await this.frame({ jsonrpc: "2.0", method, params }, this.server.requestTimeoutMs, true);
  }

  private async request(method: string, params: Record<string, unknown>, timeoutMs = this.server.requestTimeoutMs): Promise<unknown> {
    const response = await this.frame({
      id: randomUUID(),
      jsonrpc: "2.0",
      method,
      params
    }, timeoutMs, false);
    if (!isRecord(response)) {
      throw new Error(`Invalid MCP response from ${this.server.name}.`);
    }
    if (isRecord(response.error)) {
      throw new Error(`MCP request failed (${this.server.name}): ${String(response.error.message ?? "Unknown error")}`);
    }
    return response.result;
  }

  private async frame(request: Record<string, unknown>, timeoutMs = defaultRequestTimeoutMs, notification: boolean): Promise<unknown> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeoutMs);
    try {
      const headers = new Headers({
        accept: "application/json, text/event-stream",
        "content-type": "application/json",
        ...(this.server.headers ?? {})
      });
      const apiKey = this.server.apiKey || (this.server.apiKeyEnv ? process.env[this.server.apiKeyEnv] : "");
      if (apiKey && !headers.has("authorization")) {
        headers.set("authorization", `Bearer ${apiKey}`);
      }
      if (this.sessionId) {

View on GitHub (pinned to 99f24806c6)

Solutions

1. Inspect the embedded server message — it is the remote server's own error text and usually names the real cause (e.g. schema violation)
2. Validate your tool arguments against the tool's inputSchema returned by tools/list before calling
3. Verify the tool name still exists on the server (re-fetch tools/list after server upgrades)
4. If sessions expire, reconnect/re-initialize the MCP client and retry once

Example fix

// before
const result = await client.callTool("search", { q: 123 });

// after
const tools = await client.listTools();
const tool = tools.find(t => t.name === "search");
// validate args against tool.inputSchema (e.g. with ajv) before calling
const result = await client.callTool("search", { q: "hello" });

const tools = await client.listTools();
const tool = tools.find(t => t.name === toolName);
if (!tool) throw new Error(`Unknown tool: ${toolName}`);
const valid = ajv.validate(tool.inputSchema, args);
if (!valid) throw new Error(`Invalid args: ${JSON.stringify(ajv.errors)}`);

const isRpcError = (e: unknown): boolean =>
  e instanceof Error && e.message.startsWith("MCP request failed");

try {
  const result = await client.callTool(toolName, args);
} catch (e) {
  if (isRpcError(e)) {
    // server-returned error message is embedded; log and surface to user
    logger.warn(e.message);
    return { error: e.message };
  }
  throw e;
}

When it happens

Trigger: Calling any MCP tool/method through ToolHubMcpClient (request/tools/call, initialize, etc.) where the remote server replies with a JSON-RPC error object, e.g. unknown tool name, invalid tool arguments, or a server-side execution failure.

Common situations: Passing arguments that don't match the tool's input schema; calling a tool name that was renamed or removed on the server; server-side version mismatches after upgrading an MCP server; expired MCP sessions causing the server to reject subsequent requests.

Related errors

• tools/call params must include a tool name.
• MCP HTTP request failed (${this.server.name}): ${response.st
• browser_tab_activate requires tabId or session.
• browser_tab_close requires tabId or session.
• browser_navigate could not resolve an active tab.

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/5de71b2e209c8c52. Report an issue: GitHub.