fix(mcp-server): add diagnostic logging for 500 errors #1456

Scra3 · 2026-02-10T09:54:42Z

Summary

Replace fragile res.end wrapping with res.on('finish') in logging middleware — avoids conflicts with interceptResponseForErrorLogging which also wraps res.end/res.write
Log JSON-RPC method name (initialize, tools/list, tools/call, etc.) in handleMcpRequest to distinguish MCP operations in logs
Add stack traces and method context to the POST /mcp .catch() block and global Express error handler
Use Error level for 5xx, Warn for 4xx, Info for 2xx/3xx in response logging

Context

A client gets a 500 error on the second POST /mcp (0ms response time) with no useful info in the logs. The current logging was too sparse to diagnose production issues — the global error handler (which catches requireBearerAuth rejections) only logged Unhandled error: <message> with no path, no stack.

Test plan

yarn workspace @forestadmin/mcp-server test — 483 tests pass
yarn workspace @forestadmin/mcp-server build — compiles cleanly
yarn workspace @forestadmin/mcp-server lint — 0 errors

🤖 Generated with Claude Code

qltysh · 2026-02-10T09:55:43Z

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 11): buildExpressApp	1

qltysh · 2026-02-10T10:00:17Z

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.06%.

Modified Files with Diff Coverage (1)

Rating	File	% Diff	Uncovered Line #s
	packages/mcp-server/src/server.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.
Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.
File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)
- Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

Scra3 · 2026-02-10T13:46:05Z

packages/mcp-server/src/server.ts

          res.status(500).json({
            error: 'internal_server_error',
-            error_description: err.message,
+            error_description: 'Internal server error',


The global Express error handler was returning err.message directly in the HTTP response (error_description: err.message). This could leak internal details (file paths, database errors, stack traces embedded
in messages) to external clients. The detailed error is still logged server-side via logErrorWithStack, but the response now returns a generic "Internal server error" message, consistent with how the agent's
error-handling.ts sanitizes errors in production.

EnkiP · 2026-02-10T13:54:45Z

packages/mcp-server/src/server.ts

+          const mcpMethod = req.body?.method || 'unknown';
+          const err = error instanceof Error ? error : new Error(String(error));
+          logErrorWithStack(
+            this.logger,
+            `MCP Error on method '${mcpMethod}': ${err.message || error}`,
+            err,
+          );

          if (!res.headersSent) {
            res.status(500).json({
              jsonrpc: '2.0',
              error: {
                code: -32603,
-                message: (error as Error)?.message || 'Internal server error',
+                message: err.message || 'Internal server error',
              },
              id: null,
            });
+          } else {
+            this.logger(
+              'Warn',
+              `Cannot send error response (headers already sent) for method '${mcpMethod}'`,
+            );


why don't we use here the error handler defined below ?

We can't use the global error handler here because next is not available in this .catch() callback — we're inside a Promise chain, not an Express middleware. Even if we could call next(err), the global handler would do the same thing (log + check headersSent), but with less context (no mcpMethod).

Replace hardcoded port numbers with dynamically assigned ports to avoid EADDRINUSE errors in CI environments where ports may already be in use. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Improve logging to diagnose production 500 errors (0ms response, no useful info): - Replace fragile res.end wrapping with res.on('finish') in logging middleware - Log JSON-RPC method name in handleMcpRequest - Add stack traces to MCP error catch and global error handler - Log request method/path in global error handler - Use Error level for 5xx, Warn for 4xx in response logging Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ssing tests - Log a warning when error response cannot be sent because headers were already sent - Add test for Warn log level on 4xx responses - Add test for MCP error handler logging method name and stack trace Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…handler Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…anch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ror" - Catch tool handler errors and return them as isError results instead of throwing, because the MCP SDK replaces thrown messages with generic text - Expose real error messages in dev mode (isProduction: false) in the agent error handler, keeping "Unexpected error" in production for security Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove incorrect claim that MCP SDK replaces thrown error messages - Normalize non-Error values in catch handler to avoid undefined message - Fix misleading comment about arrow function context - Stop leaking error details in global error handler response Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/mcp-server/test/test-utils/get-available-port.ts

packages/mcp-server/src/server.ts

packages/agent/src/routes/system/error-handling.ts

packages/mcp-server/src/utils/tool-with-logging.ts

VincentMolinie · 2026-02-10T14:01:10Z

packages/mcp-server/src/server.ts

+  return 'Info';
+}
+
+function logErrorWithStack(logger: Logger, message: string, err: Error): void {


why taking an error and a message ? Message can be retrieved from the error 🤔

The message param adds context that err.message alone doesn't have — e.g. "MCP Error on method 'tools/call': <err.message>" or "Unhandled error on POST /mcp: <err.message>". The helper then appends the stack trace on a separate log line. So it's context + error message on line 1, stack on line 2.

Revert out-of-scope changes (isError tool handling, agent dev mode error messages) — these will be in a separate PR. Remove global error handler headersSent else branch per review feedback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

## @forestadmin/mcp-server [1.7.7](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/mcp-server@1.7.6...@forestadmin/mcp-server@1.7.7) (2026-02-10) ### Bug Fixes * **mcp-server:** add diagnostic logging for 500 errors ([#1456](#1456)) ([1e61fd7](1e61fd7)) * **mcp-server:** use random available ports in server tests ([#1457](#1457)) ([1fce1ee](1fce1ee))

Scra3 mentioned this pull request Feb 10, 2026

fix(mcp-server): use random available ports in server tests #1457

Merged

3 tasks

Scra3 force-pushed the fix/mcp-server-diagnostic-logging branch 2 times, most recently from 03e3119 to 2b97a07 Compare February 10, 2026 12:32

Scra3 changed the base branch from main to fix/mcp-server-test-random-ports February 10, 2026 12:37

Scra3 force-pushed the fix/mcp-server-diagnostic-logging branch 2 times, most recently from f205005 to dad6ffb Compare February 10, 2026 13:33

Base automatically changed from fix/mcp-server-test-random-ports to main February 10, 2026 13:41

Scra3 commented Feb 10, 2026

View reviewed changes

EnkiP reviewed Feb 10, 2026

View reviewed changes

alban bertolini and others added 10 commits February 10, 2026 14:57

fix(mcp-server): use random available ports in server tests

16f444f

Replace hardcoded port numbers with dynamically assigned ports to avoid EADDRINUSE errors in CI environments where ports may already be in use. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(mcp-server): extract getAvailablePort to reusable test util

b1b5194

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(mcp-server): fix lint import order in server tests

6f280f9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(mcp-server): clarify log format to avoid repeating 'method'

39c832a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(mcp-server): add coverage tests for headersSent and global error …

40dc348

…handler Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(mcp-server): add coverage for global error handler headersSent br…

4c8531a

…anch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Scra3 force-pushed the fix/mcp-server-diagnostic-logging branch from 2cd4749 to ffc0dd1 Compare February 10, 2026 13:57

VincentMolinie reviewed Feb 10, 2026

View reviewed changes

VincentMolinie approved these changes Feb 10, 2026

View reviewed changes

Scra3 merged commit 1e61fd7 into main Feb 10, 2026
27 checks passed

Scra3 deleted the fix/mcp-server-diagnostic-logging branch February 10, 2026 14:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(mcp-server): add diagnostic logging for 500 errors #1456

fix(mcp-server): add diagnostic logging for 500 errors #1456

Scra3 commented Feb 10, 2026

Uh oh!

qltysh bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

qltysh bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

Scra3 Feb 10, 2026

Uh oh!

EnkiP Feb 10, 2026

Uh oh!

Scra3 Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VincentMolinie Feb 10, 2026

Uh oh!

Scra3 Feb 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix(mcp-server): add diagnostic logging for 500 errors #1456

fix(mcp-server): add diagnostic logging for 500 errors #1456

Conversation

Scra3 commented Feb 10, 2026

Summary

Context

Test plan

Uh oh!

qltysh bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1 new issue

Uh oh!

qltysh bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Scra3 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

EnkiP Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Scra3 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VincentMolinie Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Scra3 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

qltysh bot commented Feb 10, 2026 •

edited

Loading

qltysh bot commented Feb 10, 2026 •

edited

Loading