Skip to content

Commit f385c94

Browse files
Tailor logging guidance to each language in build-server docs (modelcontextprotocol#1970)
The "Logging in MCP Servers" section was copy-pasted across language tabs with examples from Python, JavaScript, and Go regardless of which tab the reader was viewing. Each tab now only references its own language: - Python: `print()` with `file=sys.stderr` workaround - TypeScript: `console.log()` / `console.error()` - Java: `System.out.println()` - Kotlin: Added missing logging section with `println()` - C#: `Console.WriteLine()` - Rust: `println!()` / `print!()` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2 parents d8ba1e2 + 0a930f1 commit f385c94

1 file changed

Lines changed: 31 additions & 52 deletions

File tree

docs/docs/develop/build-server.mdx

Lines changed: 31 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -45,30 +45,27 @@ This quickstart assumes you have familiarity with:
4545

4646
When implementing MCP servers, be careful about how you handle logging:
4747

48-
**For STDIO-based servers:** Never write to standard output (stdout). This includes:
49-
50-
- `print()` statements in Python
51-
- `console.log()` in JavaScript
52-
- `fmt.Println()` in Go
53-
- Similar stdout functions in other languages
54-
55-
Writing to stdout will corrupt the JSON-RPC messages and break your server.
48+
**For STDIO-based servers:** 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, but can be used safely with `file=sys.stderr`.
5649

5750
**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.
5851

5952
### Best Practices
6053

61-
1. Use a logging library that writes to stderr or files.
62-
1. For Python, be especially careful - `print()` writes to stdout by default.
54+
- Use a logging library that writes to stderr or files.
6355

6456
### Quick Examples
6557

6658
```python
59+
import sys
60+
import logging
61+
6762
# ❌ Bad (STDIO)
6863
print("Processing request")
6964

7065
# ✅ Good (STDIO)
71-
import logging
66+
print("Processing request", file=sys.stderr)
67+
68+
# ✅ Good (STDIO)
7269
logging.info("Processing request")
7370
```
7471

@@ -369,21 +366,13 @@ This quickstart assumes you have familiarity with:
369366

370367
When implementing MCP servers, be careful about how you handle logging:
371368

372-
**For STDIO-based servers:** Never write to standard output (stdout). This includes:
373-
374-
- `print()` statements in Python
375-
- `console.log()` in JavaScript
376-
- `fmt.Println()` in Go
377-
- Similar stdout functions in other languages
378-
379-
Writing to stdout will corrupt the JSON-RPC messages and break your server.
369+
**For STDIO-based servers:** 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.
380370

381371
**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.
382372

383373
### Best Practices
384374

385-
1. Use a logging library that writes to stderr or files, such as `logging` in Python.
386-
2. For JavaScript, be especially careful - `console.log()` writes to stdout by default.
375+
- Use `console.error()` which writes to stderr, or use a logging library that writes to stderr or files.
387376

388377
### Quick Examples
389378

@@ -842,21 +831,14 @@ For manual MCP Server implementation, refer to the [MCP Server Java SDK document
842831

843832
When implementing MCP servers, be careful about how you handle logging:
844833

845-
**For STDIO-based servers:** Never write to standard output (stdout). This includes:
846-
847-
- `print()` statements in Python
848-
- `console.log()` in JavaScript
849-
- `fmt.Println()` in Go
850-
- Similar stdout functions in other languages
851-
852-
Writing to stdout will corrupt the JSON-RPC messages and break your server.
834+
**For STDIO-based servers:** 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.
853835

854836
**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.
855837

856838
### Best Practices
857839

858-
1. Use a logging library that writes to stderr or files.
859-
2. Ensure any configured logging library will not write to STDOUT
840+
- Use a logging library that writes to stderr or files.
841+
- Ensure any configured logging library will not write to stdout.
860842

861843
### System requirements
862844

@@ -1151,6 +1133,18 @@ This quickstart assumes you have familiarity with:
11511133
- Kotlin
11521134
- LLMs like Claude
11531135

1136+
### Logging in MCP Servers
1137+
1138+
When implementing MCP servers, be careful about how you handle logging:
1139+
1140+
**For STDIO-based servers:** 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.
1141+
1142+
**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.
1143+
1144+
### Best Practices
1145+
1146+
- Use a logging library that writes to stderr or files.
1147+
11541148
### System requirements
11551149

11561150
- Java 17 or higher installed.
@@ -1538,20 +1532,13 @@ This quickstart assumes you have familiarity with:
15381532

15391533
When implementing MCP servers, be careful about how you handle logging:
15401534

1541-
**For STDIO-based servers:** Never write to standard output (stdout). This includes:
1542-
1543-
- `print()` statements in Python
1544-
- `console.log()` in JavaScript
1545-
- `fmt.Println()` in Go
1546-
- Similar stdout functions in other languages
1547-
1548-
Writing to stdout will corrupt the JSON-RPC messages and break your server.
1535+
**For STDIO-based servers:** 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.
15491536

15501537
**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.
15511538

15521539
### Best Practices
15531540

1554-
1. Use a logging library that writes to stderr or files
1541+
- Use a logging library that writes to stderr or files.
15551542

15561543
### System requirements
15571544

@@ -1811,21 +1798,14 @@ This quickstart assumes you have familiarity with:
18111798

18121799
When implementing MCP servers, be careful about how you handle logging:
18131800

1814-
**For STDIO-based servers:** Never write to standard output (stdout). This includes:
1815-
1816-
- `print()` statements in Python
1817-
- `console.log()` in JavaScript
1818-
- `println!()` in Rust
1819-
- Similar stdout functions in other languages
1820-
1821-
Writing to stdout will corrupt the JSON-RPC messages and break your server.
1801+
**For STDIO-based servers:** 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.
18221802

18231803
**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.
18241804

18251805
### Best Practices
18261806

1827-
1. Use a logging library that writes to stderr or files, such as `tracing` or `log` in Rust.
1828-
2. Configure your logging framework to avoid stdout output.
1807+
- Use a logging library that writes to stderr or files, such as `tracing` or `log` in Rust.
1808+
- Configure your logging framework to avoid stdout output.
18291809

18301810
### Quick Examples
18311811

@@ -1834,8 +1814,7 @@ Writing to stdout will corrupt the JSON-RPC messages and break your server.
18341814
println!("Processing request");
18351815

18361816
// ✅ Good (STDIO)
1837-
use tracing::info;
1838-
info!("Processing request"); // writes to stderr
1817+
eprintln!("Processing request"); // writes to stderr
18391818
```
18401819

18411820
### System requirements

0 commit comments

Comments
 (0)