How to fix MCP tool execution errors

1// Successful tool response
2{
3  content: [{ type: "text", text: "Result data here" }]
4}
5
6// Error tool response — the correct way to report tool failures
7{
8  content: [{ type: "text", text: "Error: File not found at /path/to/file" }],
9  isError: true
10}
11
12// What happens if you throw instead:
13// The SDK catches it and returns a generic error:
14// { content: [{ type: "text", text: "Internal error" }], isError: true }
15// This is less helpful to the AI

1server.tool(
2  "fetch-data",
3  "Fetch data from an API",
4  { url: z.string().url() },
5  async ({ url }) => {
6    try {
7      const response = await fetch(url);
8
9      if (!response.ok) {
10        return {
11          content: [{
12            type: "text",
13            text: `API returned HTTP ${response.status}: ${response.statusText}. URL: ${url}`,
14          }],
15          isError: true,
16        };
17      }
18
19      const data = await response.json();
20      return {
21        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
22      };
23    } catch (error) {
24      const message = error instanceof Error ? error.message : String(error);
25      return {
26        content: [{
27          type: "text",
28          text: `Failed to fetch ${url}: ${message}`,
29        }],
30        isError: true,
31      };
32    }
33  }
34);

1import { z } from "zod";
2
3// WEAK validation — accepts any string, errors happen inside handler
4server.tool("search", "Search", { query: z.string() }, async ({ query }) => {
5  // If query is empty, the API might return confusing results
6});
7
8// STRONG validation — catches problems before handler runs
9server.tool(
10  "search",
11  "Search for items",
12  {
13    query: z.string()
14      .min(1, "Query cannot be empty")
15      .max(500, "Query too long, max 500 characters"),
16    category: z.enum(["docs", "code", "issues"]).optional(),
17    limit: z.number()
18      .int()
19      .min(1, "Limit must be at least 1")
20      .max(100, "Limit cannot exceed 100")
21      .optional()
22      .default(10),
23  },
24  async ({ query, category, limit }) => {
25    // Inputs are guaranteed to be valid at this point
26    console.error(`Searching: query=${query}, category=${category}, limit=${limit}`);
27    // ... handler logic
28  }
29);

1server.tool(
2  "get-repo-info",
3  "Get GitHub repository information",
4  { owner: z.string(), repo: z.string() },
5  async ({ owner, repo }) => {
6    try {
7      const response = await fetch(
8        `https://api.github.com/repos/${owner}/${repo}`,
9        { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
10      );
11
12      if (response.status === 404) {
13        return {
14          content: [{
15            type: "text",
16            text: `Repository ${owner}/${repo} not found. Check the owner and repo name are correct.`,
17          }],
18          isError: true,
19        };
20      }
21
22      if (response.status === 401) {
23        return {
24          content: [{
25            type: "text",
26            text: "GitHub authentication failed. The GITHUB_TOKEN may be expired or invalid.",
27          }],
28          isError: true,
29        };
30      }
31
32      if (response.status === 403) {
33        return {
34          content: [{
35            type: "text",
36            text: "GitHub rate limit exceeded. Wait a minute and try again.",
37          }],
38          isError: true,
39        };
40      }
41
42      const data = await response.json();
43      return {
44        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
45      };
46    } catch (error) {
47      return {
48        content: [{
49          type: "text",
50          text: `Network error: ${(error as Error).message}. Check your internet connection.`,
51        }],
52        isError: true,
53      };
54    }
55  }
56);

1server.tool(
2  "complex-operation",
3  "Perform a complex operation",
4  { input: z.string() },
5  async ({ input }) => {
6    try {
7      const result = await performComplexOperation(input);
8      return { content: [{ type: "text", text: result }] };
9    } catch (error) {
10      // Log full details to stderr (for developer debugging)
11      console.error("Tool 'complex-operation' failed:");
12      console.error(`  Input: ${input}`);
13      console.error(`  Error: ${(error as Error).stack}`);
14
15      // Return clean message to AI (for user experience)
16      return {
17        content: [{
18          type: "text",
19          text: `The operation failed: ${(error as Error).message}. Try with different input or check the server logs for details.`,
20        }],
21        isError: true,
22      };
23    }
24  }
25);