MCP · Building servers and clients · all subjects

common mistakes & debugging

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Never write to stdout in STDIO-based servers (Python)

For STDIO-based servers in Python, never write to stdout. Writing to stdout will corrupt the JSON-RPC messages and break your server. The print() function writes to stdout by default, so keep it out of a STDIO server entirely. Use the standard library logging module which writes to stderr instead.

Never use console.log in STDIO-based servers (TypeScript)

For STDIO-based servers in TypeScript, never use console.log() as it writes to standard output (stdout) by default. Writing to stdout will corrupt the JSON-RPC messages and break your server. Use console.error() which writes to stderr, or use a logging library that writes to stderr or files.

Never use System.out.println in STDIO-based servers (Java)

For STDIO-based servers in Java, never use System.out.println() or System.out.print() as they write to standard output (stdout). Writing to stdout will corrupt the JSON-RPC messages and break your server. Use a logging library that writes to stderr or files.

Never use println() in STDIO-based servers (Kotlin)

For STDIO-based servers in Kotlin, never use println() as it writes to standard output (stdout) by default. Writing to stdout will corrupt the JSON-RPC messages and break your server. Use a logging library that writes to stderr or files.

Never use Console.WriteLine in STDIO-based servers (C#)

For STDIO-based servers in C#, never use Console.WriteLine() or Console.Write() as they write to standard output (stdout). Writing to stdout will corrupt the JSON-RPC messages and break your server. Use a logging library that writes to stderr or files.

Never use puts or print in STDIO-based servers (Ruby)

For STDIO-based servers in Ruby, never use puts or print as they write to standard output (stdout) by default. Writing to stdout will corrupt the JSON-RPC messages and break your server. Use a logging library that writes to stderr or files.

Never use println! in STDIO-based servers (Rust)

For STDIO-based servers in Rust, never use println!() or print!() as they write to standard output (stdout). Writing to stdout will corrupt the JSON-RPC messages and break your server. Use eprintln!() which writes to stderr, or use a logging library such as tracing or log that writes to stderr or files.

HTTP-based servers can use standard output logging

For HTTP-based servers, standard output logging is fine since it doesn't interfere with HTTP responses. Logging restrictions only apply to STDIO-based servers.

TypeScript: npm run build step is required

In TypeScript MCP servers, running npm run build to compile TypeScript to JavaScript is a required step before connecting the server to a client. The compiled output in the build directory is what gets executed.

C# MCP server: Host.CreateEmptyApplicationBuilder for STDIO

In C#, use Host.CreateEmptyApplicationBuilder(settings: null) instead of CreateDefaultBuilder for STDIO servers. This ensures the server does not write additional messages to the console.

Claude for Desktop: absolute paths required in config

In Claude for Desktop configuration, always use absolute paths for server locations. Relative paths will not work. On Windows, use double backslashes (\\) or forward slashes (/) in JSON paths.

Go MCP server logging must avoid stdout for stdio transport

For stdio-based MCP servers in Go, never use fmt.Println() or fmt.Printf() as they write to stdout and corrupt JSON-RPC messages. Instead use log.Println() which defaults to stderr, or fmt.Fprintf(os.Stderr, ...) to write explicitly to stderr.

Claude for Desktop requires absolute paths in config

MCP server paths in claude_desktop_config.json must be absolute, not relative. On Windows, use double backslashes (\\) or forward slashes (/) in JSON paths and add .exe extension. Relative paths will cause the server not to be recognized.

Claude for Desktop requires full application restart for config changes

To apply MCP server configuration changes in Claude for Desktop, fully quit the application: use Cmd+Q on macOS, right-click system tray and select Quit on Windows/Linux, or pkill -f claude-desktop. Simply closing the window does not fully quit and changes will not take effect.

Give your agent this brain