Skip to content

Commit 2c0a763

Browse files
mattpodwysockimattpodwysocki
committed
[otel] Update Server docs with OTEL information
1 parent 072bdd6 commit 2c0a763

12 files changed

Lines changed: 119 additions & 186 deletions

‎.env.example‎

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,6 @@
99
# Get your token at: https://account.mapbox.com/access-tokens
1010
MAPBOX_ACCESS_TOKEN=your-mapbox-token-here
1111

12-
# =============================================================================
13-
# Optional MCP Configuration
14-
# =============================================================================
15-
16-
# Disable console logging (recommended when using stdio transport)
17-
# Uncomment to enable:
18-
# MCP_LOGGING_DISABLE=true
19-
2012
# =============================================================================
2113
# OpenTelemetry Tracing (Optional)
2214
# =============================================================================
@@ -35,13 +27,11 @@ OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
3527
# Resource attributes (customize as needed)
3628
OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5
3729

38-
# Optional: Console tracing for development (SSE transport only)
39-
# ⚠️ Do NOT enable with stdio transport - it breaks JSON-RPC communication
40-
# OTEL_EXPORTER_CONSOLE_ENABLED=true
41-
42-
# Optional: OTEL diagnostic log level (default: NONE to avoid stdio pollution)
43-
# Set to DEBUG, INFO, WARN, or ERROR for troubleshooting OTEL issues
44-
# ⚠️ Only use for debugging - logs will corrupt stdio transport
30+
# Optional: OTEL diagnostic log level (default: NONE)
31+
# This server uses stdio transport exclusively. OTEL diagnostic logs are disabled
32+
# by default to prevent corrupting JSON-RPC communication.
33+
# Set to DEBUG, INFO, WARN, or ERROR only for troubleshooting OTEL configuration issues.
34+
# Valid values: NONE (default), ERROR, WARN, INFO, DEBUG, VERBOSE
4535
# OTEL_LOG_LEVEL=ERROR
4636

4737
# Optional: OTLP authentication headers (for production backends)

‎CLAUDE.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,10 @@ This server includes OpenTelemetry (OTEL) instrumentation for distributed tracin
5656
### Environment Variables
5757

5858
- `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL (e.g., `http://localhost:4318`). If not set, tracing is disabled.
59-
- `OTEL_EXPORTER_CONSOLE_ENABLED` — Set to `true` to log traces to console (avoid with stdio transport)
6059
- `OTEL_TRACING_ENABLED` — Set to `false` to explicitly disable tracing even if endpoint is configured
6160
- `OTEL_SERVICE_NAME` — Override service name (default: `mapbox-mcp-devkit-server`)
6261
- `OTEL_EXPORTER_OTLP_HEADERS` — JSON string of additional headers for OTLP exporter
63-
- `OTEL_LOG_LEVEL` — OTEL diagnostic log level: `NONE` (default), `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`. Set to `NONE` to prevent OTEL logs from polluting stdio transport.
62+
- `OTEL_LOG_LEVEL` — OTEL diagnostic log level: `NONE` (default), `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`. Defaults to `NONE` to prevent diagnostic logs from corrupting stdio transport.
6463

6564
### What Gets Traced
6665

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -610,7 +610,7 @@ npm run inspect:build
610610
docker build -t mapbox-mcp-devkit .
611611

612612
# Run and inspect the server
613-
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" --env MCP_LOGGING_DISABLE="true" mapbox-mcp-devkit
613+
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-devkit
614614
```
615615

616616
### Creating New Tools

‎docs/claude-code-integration.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,7 @@ Add to your Claude Code MCP configuration:
6060
"command": "npx",
6161
"args": ["-y", "@mapbox/mcp-devkit-server"],
6262
"env": {
63-
"MAPBOX_ACCESS_TOKEN": "your_token_here",
64-
"MCP_LOGGING_DISABLE": "true"
63+
"MAPBOX_ACCESS_TOKEN": "your_token_here"
6564
}
6665
}
6766
}
@@ -81,8 +80,6 @@ Add to your Claude Code MCP configuration:
8180
"--rm",
8281
"-e",
8382
"MAPBOX_ACCESS_TOKEN=your_token_here",
84-
"-e",
85-
"MCP_LOGGING_DISABLE": "true",
8683
"mapbox-mcp-devkit"
8784
]
8885
}
@@ -101,8 +98,7 @@ If you want to use a local version (need to clone and build from this repo):
10198
"command": "/path/to/your/node",
10299
"args": ["/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
103100
"env": {
104-
"MAPBOX_ACCESS_TOKEN": "your_token_here",
105-
"MCP_LOGGING_DISABLE": "true"
101+
"MAPBOX_ACCESS_TOKEN": "your_token_here"
106102
}
107103
}
108104
}
@@ -200,7 +196,6 @@ Enable verbose error reporting by adding the environment variable:
200196
"args": ["-y", "@mapbox/mcp-devkit-server"],
201197
"env": {
202198
"MAPBOX_ACCESS_TOKEN": "your_token_here",
203-
"MCP_LOGGING_DISABLE": "true",
204199
"VERBOSE_ERRORS": "true"
205200
}
206201
}

‎docs/claude-desktop-integration.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,7 @@ For users who prefer manual configuration or need custom setups, you can configu
7171
"command": "npx",
7272
"args": ["-y", "@mapbox/mcp-devkit-server"],
7373
"env": {
74-
"MAPBOX_ACCESS_TOKEN": "your_token_here",
75-
"MCP_LOGGING_DISABLE": "true"
74+
"MAPBOX_ACCESS_TOKEN": "your_token_here"
7675
}
7776
}
7877
}
@@ -92,8 +91,6 @@ For users who prefer manual configuration or need custom setups, you can configu
9291
"--rm",
9392
"-e",
9493
"MAPBOX_ACCESS_TOKEN=your_token_here",
95-
"-e",
96-
"MCP_LOGGING_DISABLE": "true",
9794
"mapbox-mcp-devkit"
9895
]
9996
}
@@ -112,8 +109,7 @@ If you want to use a local version (need to clone and build from this repo):
112109
"command": "/path/to/your/node",
113110
"args": ["/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
114111
"env": {
115-
"MAPBOX_ACCESS_TOKEN": "your_token_here",
116-
"MCP_LOGGING_DISABLE": "true"
112+
"MAPBOX_ACCESS_TOKEN": "your_token_here"
117113
}
118114
}
119115
}
@@ -184,7 +180,6 @@ Enable verbose error reporting by adding the environment variable:
184180
"args": ["-y", "@mapbox/mcp-devkit-server"],
185181
"env": {
186182
"MAPBOX_ACCESS_TOKEN": "your_token_here",
187-
"MCP_LOGGING_DISABLE": "true"
188183
"VERBOSE_ERRORS": "true"
189184
}
190185
}

‎docs/cursor-integration.md‎

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,7 @@ docker build -t mapbox-mcp-devkit .
3232
"command": "npx",
3333
"args": ["-y", "@mapbox/mcp-devkit-server"],
3434
"env": {
35-
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>",
36-
"MCP_LOGGING_DISABLE": "true"
35+
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
3736
}
3837
}
3938
}
@@ -54,8 +53,6 @@ docker build -t mapbox-mcp-devkit .
5453
"--rm",
5554
"--env",
5655
"MAPBOX_ACCESS_TOKEN=<YOUR_TOKEN>",
57-
"--env",
58-
"MCP_LOGGING_DISABLE=true",
5956
"mapbox-mcp-devkit"
6057
]
6158
}
@@ -72,8 +69,7 @@ docker build -t mapbox-mcp-devkit .
7269
"command": "node",
7370
"args": ["<ABSOLUTE_PATH_TO_REPO>/dist/esm/index.js"],
7471
"env": {
75-
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>",
76-
"MCP_LOGGING_DISABLE": "true"
72+
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
7773
}
7874
}
7975
}
@@ -84,10 +80,6 @@ docker build -t mapbox-mcp-devkit .
8480

8581
## Important Notes
8682

87-
### Stdio Transport Logging
88-
89-
The MCP DevKit Server uses stdio (standard input/output) for communication with Cursor. To prevent console logs from corrupting the JSON-RPC protocol, **you must set `MCP_LOGGING_DISABLE=true`** in the environment variables.
90-
9183
### Token Scopes
9284

9385
Your Mapbox access token must have the appropriate scopes for the tools you want to use. See the [main README](../README.md#tools) for required token scopes per tool.
@@ -143,9 +135,8 @@ If you get "command not found" errors for `node` or `npx`:
143135

144136
If you see JSON-RPC or parsing errors:
145137

146-
1. Ensure `MCP_LOGGING_DISABLE` is set to `"true"` in your configuration
147-
2. If using Node version, verify the path to `dist/esm/index.js` is correct
148-
3. Run `npm run build` to ensure the latest build is available
138+
1. If using Node version, verify the path to `dist/esm/index.js` is correct
139+
2. Run `npm run build` to ensure the latest build is available
149140

150141
### Tool Execution Failures
151142

‎docs/tracing-verification.md‎

Lines changed: 6 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -73,9 +73,7 @@ npm run tracing:jaeger:stop
7373

7474
### Successful Tracing Setup
7575

76-
✅ **Console output shows**: `OpenTelemetry tracing: enabled`
77-
78-
✅ **Jaeger UI shows traces** for your service
76+
✅ **Jaeger UI shows traces** for your service after tool execution
7977

8078
✅ **Trace details include**:
8179

@@ -193,34 +191,16 @@ OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io/v1/traces
193191
OTEL_EXPORTER_OTLP_HEADERS='{"x-honeycomb-team":"YOUR_API_KEY"}'
194192
```
195193

196-
## Alternative Methods
197-
198-
### Console Tracing (Development Only)
199-
200-
**⚠️ Not recommended for stdio transport**
201-
202-
```bash
203-
# Add to .env (only works well with SSE transport)
204-
OTEL_EXPORTER_CONSOLE_ENABLED=true
205-
```
206-
207-
This prints traces to stderr. Only use this for debugging, as it can interfere with MCP's stdio communication.
208-
209-
### Verifying Different Transports
194+
## Diagnostic Logging
210195

211-
#### stdio Transport (Default) - Silent Operation
196+
By default, OpenTelemetry diagnostic logs are disabled to prevent interference with stdio transport. If you need to troubleshoot OTEL configuration issues, you can enable diagnostic logging:
212197

213198
```bash
214-
# Normal operation
215-
npm run inspect:build
199+
# Add to .env - only for debugging OTEL issues
200+
OTEL_LOG_LEVEL=ERROR
216201
```
217202

218-
#### SSE Transport - Full Logging
219-
220-
```bash
221-
# If your inspector supports SSE transport
222-
SERVER_TRANSPORT=sse npm run inspect:build
223-
```
203+
**⚠️ Warning:** Any console output (including OTEL diagnostic logs) can corrupt stdio communication. Only enable diagnostic logging when actively troubleshooting, and disable it once resolved.
224204

225205
## Production Considerations
226206

‎docs/tracing.md‎

Lines changed: 17 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,11 @@
22

33
This MCP server includes comprehensive distributed tracing using OpenTelemetry (OTEL), providing production-ready observability for tool executions and HTTP requests.
44

5-
## ⚠️ Important MCP Transport Compatibility
5+
## ⚠️ Important: Stdio Transport Only
66

7-
**Console tracing should be avoided with stdio transport** as console output interferes with MCP's stdio JSON-RPC communication.
7+
**This server uses stdio transport exclusively.** Only OTLP exporters are supported for tracing.
88

9-
**Transport-specific recommendations:**
10-
11-
- **stdio transport (default):** Use OTLP exporters only, avoid console tracing
12-
- **SSE transport:** Console tracing is safe to use for development
13-
14-
The server automatically detects the transport type and adjusts logging behavior accordingly.
9+
Console output is incompatible with stdio and will corrupt JSON-RPC communication. All diagnostic logging is disabled by default to ensure reliable operation.
1510

1611
## Features
1712

@@ -56,14 +51,15 @@ The tracing system supports several configuration options through environment va
5651
#### Basic Configuration
5752

5853
```bash
59-
# Enable console tracing (development)
60-
OTEL_EXPORTER_CONSOLE_ENABLED=true
61-
62-
# OTLP HTTP endpoint (production)
54+
# OTLP HTTP endpoint (required to enable tracing)
6355
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
6456

6557
# Optional OTLP headers for authentication
6658
OTEL_EXPORTER_OTLP_HEADERS='{"Authorization": "Bearer your-token"}'
59+
60+
# Optional: OTEL diagnostic log level (default: NONE)
61+
# Only use for troubleshooting OTEL configuration issues
62+
OTEL_LOG_LEVEL=ERROR
6763
```
6864

6965
#### Service Configuration
@@ -82,29 +78,23 @@ OTEL_TRACES_SAMPLER=traceidratio
8278
OTEL_TRACES_SAMPLER_ARG=0.1 # Sample 10% of traces
8379
```
8480

85-
### Transport-Specific Configuration
81+
### Enabling Tracing
8682

87-
**For stdio transport (default):**
83+
Tracing is opt-in and disabled by default. To enable tracing, you must configure an OTLP endpoint:
8884

8985
```bash
90-
# ✅ RECOMMENDED: Use OTLP exporter for stdio transport
86+
# Enable tracing by setting the OTLP endpoint
9187
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
9288

93-
# ❌ AVOID: Console output interferes with stdio JSON-RPC
94-
# OTEL_EXPORTER_CONSOLE_ENABLED=true
95-
```
96-
97-
**For SSE transport:**
98-
99-
```bash
100-
# ✅ SAFE: Console tracing works with SSE transport
101-
SERVER_TRANSPORT=sse
102-
OTEL_EXPORTER_CONSOLE_ENABLED=true
89+
# Optionally customize the service name
90+
OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
10391

104-
# ✅ ALSO GOOD: OTLP exporter works with any transport
105-
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
92+
# For debugging OTEL configuration issues only
93+
# OTEL_LOG_LEVEL=ERROR
10694
```
10795

96+
**Note:** Console exporters are not supported due to stdio transport limitations.
97+
10898
### Verification
10999

110100
To verify tracing is working correctly, see the [Tracing Verification Guide](./tracing-verification.md) which shows how to:

‎docs/vscode-integration.md‎

Lines changed: 6 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,7 @@ docker build -t mapbox-mcp-devkit .
3737
"command": "npx",
3838
"args": ["-y", "@mapbox/mcp-devkit-server"],
3939
"env": {
40-
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>",
41-
"MCP_LOGGING_DISABLE": "true"
40+
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
4241
}
4342
}
4443
}
@@ -59,8 +58,6 @@ docker build -t mapbox-mcp-devkit .
5958
"--rm",
6059
"--env",
6160
"MAPBOX_ACCESS_TOKEN=<YOUR_TOKEN>",
62-
"--env",
63-
"MCP_LOGGING_DISABLE=true",
6461
"mapbox-mcp-devkit"
6562
]
6663
}
@@ -79,8 +76,7 @@ docker build -t mapbox-mcp-devkit .
7976
"<ABSOLUTE_PATH_TO_REPO>/dist/esm/index.js"
8077
],
8178
"env": {
82-
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>",
83-
"MCP_LOGGING_DISABLE": "true"
79+
"MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
8480
}
8581
}
8682
}
@@ -97,10 +93,6 @@ After restarting VS Code, you should see "Mapbox DevKit" appear in the GitHub Co
9793

9894
## Important Notes
9995

100-
### Stdio Transport Logging
101-
102-
The MCP DevKit Server uses stdio (standard input/output) for communication with VS Code. To prevent console logs from corrupting the JSON-RPC protocol, **you must set `MCP_LOGGING_DISABLE=true`** in the environment variables.
103-
10496
### Token Scopes
10597

10698
Your Mapbox access token must have the appropriate scopes for the tools you want to use. See the [main README](../README.md#tools) for required token scopes per tool.
@@ -128,8 +120,7 @@ Here's a complete `settings.json` example with the NPM version:
128120
"command": "npx",
129121
"args": ["-y", "@mapbox/mcp-devkit-server"],
130122
"env": {
131-
"MAPBOX_ACCESS_TOKEN": "pk.eyJ1IjoiZXhhbXBsZSIsImEiOiJjbGV4YW1wbGUifQ.example",
132-
"MCP_LOGGING_DISABLE": "true"
123+
"MAPBOX_ACCESS_TOKEN": "pk.eyJ1IjoiZXhhbXBsZSIsImEiOiJjbGV4YW1wbGUifQ.example"
133124
}
134125
}
135126
}
@@ -153,9 +144,9 @@ If the Mapbox DevKit Server doesn't appear in VS Code's MCP servers:
153144

154145
If you see JSON-RPC or parsing errors in the Output panel:
155146

156-
1. **Logging disabled**: Ensure `MCP_LOGGING_DISABLE` is set to `"true"` in your configuration
157-
2. **Build fresh**: Run `npm run build` to ensure you have the latest build
158-
3. **Path verification**: For Node version, verify the path to `dist/esm/index.js` is correct and absolute
147+
1. **Build fresh**: Run `npm run build` to ensure you have the latest build
148+
2. **Path verification**: For Node version, verify the path to `dist/esm/index.js` is correct and absolute
149+
3. **Check logs**: Open "Output" panel → Select "MCP" from dropdown to see detailed logs
159150

160151
### Tool Execution Failures
161152

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@
1414
"format": "prettier --check \"./src/**/*.{ts,tsx,js,json,md}\" \"./test/**/*.{ts,tsx,js,json,md}\"",
1515
"format:fix": "prettier --write \"./src/**/*.{ts,tsx,js,json,md}\" \"./test/**/*.{ts,tsx,js,json,md}\"",
1616
"generate-version": "node scripts/build-helpers.cjs generate-version",
17-
"inspect:build": "npm run build && npx @modelcontextprotocol/inspector -e MAPBOX_ACCESS_TOKEN=\"$MAPBOX_ACCESS_TOKEN\" -e MCP_LOGGING_DISABLE=true node dist/esm/index.js",
18-
"inspect:dev": "npx @modelcontextprotocol/inspector -e MAPBOX_ACCESS_TOKEN=\"$MAPBOX_ACCESS_TOKEN\" -e MCP_LOGGING_DISABLE=true npx -y tsx src/index.ts",
17+
"inspect:build": "npm run build && npx @modelcontextprotocol/inspector -e MAPBOX_ACCESS_TOKEN=\"$MAPBOX_ACCESS_TOKEN\" node dist/esm/index.js",
18+
"inspect:dev": "npx @modelcontextprotocol/inspector -e MAPBOX_ACCESS_TOKEN=\"$MAPBOX_ACCESS_TOKEN\" npx -y tsx src/index.ts",
1919
"lint": "eslint \"./src/**/*.{ts,tsx}\" \"./test/**/*.{ts,tsx}\"",
2020
"lint:fix": "eslint \"./src/**/*.{ts,tsx}\" \"./test/**/*.{ts,tsx}\" --fix",
2121
"prepare": "husky && node .husky/setup-hooks.js",

0 commit comments

Comments
 (0)