Follow MCP best practices: add isError flag to tool responses

Copilot · Andrew-Paystack · Copilot · commit c89d3469885d · 2026-02-23T17:03:50.000Z
- Updated make-paystack-request tool to return isError: true on failures
- Updated get-paystack-operation tool to return isError: true on failures
- Enhanced error messages to include HTTP status codes
- Added comprehensive test suite for tool-level error handling
- All 9 tests passing (4 new tool tests + 5 existing client tests)

Co-authored-by: Andrew-Paystack &lt;78197464+Andrew-Paystack@users.noreply.github.com&gt;
diff --git a/src/tools/get-paystack-operation.ts b/src/tools/get-paystack-operation.ts
@@ -34,7 +34,8 @@ export function registerGetPaystackOperationTool(
                 type: "text",
                 text: `Operation with ID ${operation_id} not found.`,
               },
-            ]
+            ],
+            isError: true
           }
         }
 
@@ -47,14 +48,16 @@ export function registerGetPaystackOperationTool(
             },
           ]
         }
-      } catch {
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
         return {
           content: [
             {
               type: "text",
-              text: `Operation with ID ${operation_id} not found.`,
+              text: `Unable to retrieve operation: ${errorMessage}`,
             },
-          ]
+          ],
+          isError: true
         }
       }
     }
diff --git a/src/tools/make-paystack-request.ts b/src/tools/make-paystack-request.ts
@@ -38,13 +38,23 @@ export function registerMakePaystackRequestTool(server: McpServer) {
           ]
         }
       } catch(error) {
+        // Follow MCP best practices: return isError flag instead of throwing
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const statusCode = (error as any).statusCode;
+        
+        let detailedMessage = `Unable to make request: ${errorMessage}`;
+        if (statusCode) {
+          detailedMessage = `Unable to make request (HTTP ${statusCode}): ${errorMessage}`;
+        }
+
         return {
           content: [
             {
               type: "text",
-              text: `Unable to make request. ${error}`,
+              text: detailedMessage,
             },
-          ]
+          ],
+          isError: true
         }
       }
     }
diff --git a/test/make-paystack-request-tool.spec.ts b/test/make-paystack-request-tool.spec.ts
@@ -0,0 +1,148 @@
+import assert from "node:assert";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerMakePaystackRequestTool } from "../src/tools/make-paystack-request.js";
+
+describe("MakePaystackRequestTool", () => {
+  describe("Error handling with isError flag", () => {
+    let server: McpServer;
+    let toolHandler: any;
+
+    before(() => {
+      // Create a mock MCP server
+      server = {
+        registerTool: (name: string, config: any, handler: any) => {
+          if (name === "make_paystack_request") {
+            toolHandler = handler;
+          }
+        }
+      } as any;
+
+      registerMakePaystackRequestTool(server);
+    });
+
+    it("should return isError: true for non-JSON responses", async () => {
+      // Mock fetch to return HTML error page
+      const originalFetch = global.fetch;
+      global.fetch = async () => {
+        return {
+          status: 502,
+          text: async () => "<html><body><h1>502 Bad Gateway</h1></body></html>",
+        } as Response;
+      };
+
+      try {
+        const result = await toolHandler({
+          request: {
+            method: "GET",
+            path: "/test-endpoint",
+          }
+        });
+
+        // Verify isError flag is set
+        assert.strictEqual(result.isError, true);
+        
+        // Verify error message content
+        assert.ok(result.content);
+        assert.strictEqual(result.content.length, 1);
+        assert.strictEqual(result.content[0].type, "text");
+        assert.ok(result.content[0].text.includes("Unable to make request"));
+        assert.ok(result.content[0].text.includes("HTTP 502"));
+        assert.ok(result.content[0].text.includes("non-JSON response"));
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it("should return isError: false (omitted) for successful responses", async () => {
+      // Mock fetch to return valid JSON
+      const originalFetch = global.fetch;
+      const validJsonResponse = {
+        status: true,
+        message: "Success",
+        data: { id: 123 }
+      };
+      
+      global.fetch = async () => {
+        return {
+          status: 200,
+          text: async () => JSON.stringify(validJsonResponse),
+        } as Response;
+      };
+
+      try {
+        const result = await toolHandler({
+          request: {
+            method: "GET",
+            path: "/test-endpoint",
+          }
+        });
+
+        // Verify isError is not set (or false) for successful responses
+        assert.ok(!result.isError);
+        
+        // Verify success content
+        assert.ok(result.content);
+        assert.strictEqual(result.content.length, 1);
+        assert.strictEqual(result.content[0].type, "text");
+        assert.strictEqual(result.content[0].mimeType, "application/json");
+        
+        // Parse and verify the response data
+        const parsedResponse = JSON.parse(result.content[0].text);
+        assert.strictEqual(parsedResponse.status, true);
+        assert.strictEqual(parsedResponse.message, "Success");
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it("should include HTTP status code in error message", async () => {
+      // Mock fetch to return a 504 Gateway Timeout
+      const originalFetch = global.fetch;
+      global.fetch = async () => {
+        return {
+          status: 504,
+          text: async () => "Gateway Timeout",
+        } as Response;
+      };
+
+      try {
+        const result = await toolHandler({
+          request: {
+            method: "POST",
+            path: "/transaction/initialize",
+            data: { amount: 1000 }
+          }
+        });
+
+        // Verify error response structure
+        assert.strictEqual(result.isError, true);
+        assert.ok(result.content[0].text.includes("HTTP 504"));
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it("should handle network errors with isError flag", async () => {
+      // Mock fetch to simulate network error
+      const originalFetch = global.fetch;
+      global.fetch = async () => {
+        throw new Error("Network connection failed");
+      };
+
+      try {
+        const result = await toolHandler({
+          request: {
+            method: "GET",
+            path: "/customer/list",
+          }
+        });
+
+        // Verify error is properly handled
+        assert.strictEqual(result.isError, true);
+        assert.ok(result.content[0].text.includes("Unable to make request"));
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,8 @@ export function registerGetPaystackOperationTool(`
`34`	`34`	`type: "text",`
`35`	`35`	text: `Operation with ID ${operation_id} not found.`,
`36`	`36`	`},`
`37`		`- ]`
	`37`	`+ ],`
	`38`	`+ isError: true`
`38`	`39`	`}`
`39`	`40`	`}`
`40`	`41`
`@@ -47,14 +48,16 @@ export function registerGetPaystackOperationTool(`
`47`	`48`	`},`
`48`	`49`	`]`
`49`	`50`	`}`
`50`		`- } catch {`
	`51`	`+ } catch (error) {`
	`52`	`+ const errorMessage = error instanceof Error ? error.message : String(error);`
`51`	`53`	`return {`
`52`	`54`	`content: [`
`53`	`55`	`{`
`54`	`56`	`type: "text",`
`55`		- text: `Operation with ID ${operation_id} not found.`,
	`57`	+ text: `Unable to retrieve operation: ${errorMessage}`,
`56`	`58`	`},`
`57`		`- ]`
	`59`	`+ ],`
	`60`	`+ isError: true`
`58`	`61`	`}`
`59`	`62`	`}`
`60`	`63`	`}`
Original file line number	Diff line number	Diff line change
`@@ -38,13 +38,23 @@ export function registerMakePaystackRequestTool(server: McpServer) {`
`38`	`38`	`]`
`39`	`39`	`}`
`40`	`40`	`} catch(error) {`
	`41`	`+ // Follow MCP best practices: return isError flag instead of throwing`
	`42`	`+ const errorMessage = error instanceof Error ? error.message : String(error);`
	`43`	`+ const statusCode = (error as any).statusCode;`
	`44`	`+`
	`45`	+ let detailedMessage = `Unable to make request: ${errorMessage}`;
	`46`	`+ if (statusCode) {`
	`47`	+ detailedMessage = `Unable to make request (HTTP ${statusCode}): ${errorMessage}`;
	`48`	`+ }`
	`49`	`+`
`41`	`50`	`return {`
`42`	`51`	`content: [`
`43`	`52`	`{`
`44`	`53`	`type: "text",`
`45`		- text: `Unable to make request. ${error}`,
	`54`	`+ text: detailedMessage,`
`46`	`55`	`},`
`47`		`- ]`
	`56`	`+ ],`
	`57`	`+ isError: true`
`48`	`58`	`}`
`49`	`59`	`}`
`50`	`60`	`}`