From fc65e6a1d128df9f7c8dc62be26925a1e240bed8 Mon Sep 17 00:00:00 2001 From: dchaudhari7177 Date: Wed, 12 Aug 2026 22:37:27 +0530 Subject: [PATCH] docs: add a troubleshooting guide for MCP server startup failures Covers the four failure modes from the issue - server fails to start, scan times out, empty tool listing, rate limiting - plus what to include when reporting. Linked from the README docs list. Two corrections to the suggested content, because the flags it named do not exist: - There is no --timeout flag on scan/score/test; --timeout is only on `demo`. The scan timeout is the per-target `timeoutMs` field in a target config passed with --target, defaulting to 10s in runner.ts. Documented that way, with a worked config. - There is no --verbose flag anywhere in the CLI. Documented --format json instead, which carries the per-check evidence and any captured fatal error. Every flag and config field referenced was checked against src/ before being written down: --target, --format, --invoke-tools, --interval, and the timeoutMs / env / skipInvoke target-config fields. Also drops the "avoid running as root" line into a security framing rather than a generic warning: running an untrusted MCP server as root hands it root, which is the risk this tool measures. Co-Authored-By: Claude Opus 5 --- README.md | 2 +- docs/troubleshooting.md | 154 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index da762af7..a2d94308 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ Observatory gives maintainers and teams: - **MCP server mode** so agents can inspect other MCP servers directly - **Production support path** for hosted history, private repo reporting, owner-ready remediation, support, and fleet visibility -See the [launch page](./docs/launch.md), [GitHub Code Scanning for MCP servers](./docs/github-code-scanning-for-mcp.md), [Code Scanning demo](./docs/code-scanning-demo.md), [target gallery](./docs/target-gallery.md), [target registry](./docs/target-registry.md), [target contribution guide](./docs/target-contribution-guide.md), [MCP Observatory Contributors](./docs/contributor-recognition.md), [Agent Task Pack](./docs/agent-tasks.md), [MCP Receipts](./docs/mcp-receipts.md), [Tool-call receipts](./docs/tool-call-receipts.md), [MCP Risk Graph](./docs/receipt-graph.md), [`setup-ci --doctor`](./docs/setup-ci-doctor.md), [MCP server security field guide](./docs/mcp-security-field-guide.md), [Safety Methodology](./docs/methodology.md), [MCP Server Safety Index](./docs/mcp-server-safety-index.md), [June 2026 safety field report](./docs/mcp-safety-field-report-2026-06.md), [reference evaluations](./docs/reference-evaluations.md), [MCP lock files](./docs/mcp-lock-files.md), [public proof](./docs/proof.md), [campaign attribution](./docs/campaign-attribution.md), [hosted client contract](./docs/api.md), [repository boundary](./docs/repository-boundary.md), [open core boundary](./docs/commercial-boundary.md), [MCP Attack Simulation Evidence Pack](./docs/attack-simulation-pilot.md), and [commercial support](./COMMERCIAL.md). +See the [launch page](./docs/launch.md), [GitHub Code Scanning for MCP servers](./docs/github-code-scanning-for-mcp.md), [Code Scanning demo](./docs/code-scanning-demo.md), [target gallery](./docs/target-gallery.md), [target registry](./docs/target-registry.md), [target contribution guide](./docs/target-contribution-guide.md), [MCP Observatory Contributors](./docs/contributor-recognition.md), [Agent Task Pack](./docs/agent-tasks.md), [MCP Receipts](./docs/mcp-receipts.md), [Tool-call receipts](./docs/tool-call-receipts.md), [MCP Risk Graph](./docs/receipt-graph.md), [`setup-ci --doctor`](./docs/setup-ci-doctor.md), [MCP server security field guide](./docs/mcp-security-field-guide.md), [Troubleshooting](./docs/troubleshooting.md), [Safety Methodology](./docs/methodology.md), [MCP Server Safety Index](./docs/mcp-server-safety-index.md), [June 2026 safety field report](./docs/mcp-safety-field-report-2026-06.md), [reference evaluations](./docs/reference-evaluations.md), [MCP lock files](./docs/mcp-lock-files.md), [public proof](./docs/proof.md), [campaign attribution](./docs/campaign-attribution.md), [hosted client contract](./docs/api.md), [repository boundary](./docs/repository-boundary.md), [open core boundary](./docs/commercial-boundary.md), [MCP Attack Simulation Evidence Pack](./docs/attack-simulation-pilot.md), and [commercial support](./COMMERCIAL.md). ### Self-Assessment diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..57847025 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,154 @@ +# Troubleshooting + +Common failures when pointing `mcp-observatory` at an MCP server, and what to do +about them. + +Every example below uses `scan`, but the same applies to `score`, `test` and +`check` — they all launch the target the same way. + +--- + +## Server fails to start + +### `command not found` + +The target command isn't on `PATH`. Either install the server, or let `npx` +fetch it: + +```bash +mcp-observatory scan npx -y @modelcontextprotocol/server-filesystem /tmp +``` + +If you're pointing at a local build, give the interpreter and an **absolute** +path rather than relying on the shell: + +```bash +mcp-observatory scan node /abs/path/to/server/dist/index.js +``` + +### `EACCES permission denied` + +The entry point isn't executable, or a path in the server's arguments isn't +readable by your user. + +- `chmod +x` the entry script if it's invoked directly. +- Check the directories you pass as server arguments are readable. +- Don't reach for `sudo`. Running an untrusted MCP server as root hands it root, + which is exactly the risk this tool exists to measure. + +### `port already in use` / `EADDRINUSE` + +Only affects servers that bind a port (HTTP targets, or `mcp-observatory serve`). +Something is already listening — usually a previous run that didn't exit. + +```bash +# find it, then stop it +lsof -i :3000 # macOS / Linux +netstat -ano | findstr :3000 # Windows +``` + +### The process starts, then exits immediately + +Most often a missing required environment variable — many servers exit on +startup when a key is absent. See *Tool listing returns empty* below. + +--- + +## Scan times out + +The default per-target timeout is **10 seconds** (`runner.ts`), and a slow +`npx` cold start alone can eat that. + +There is **no `--timeout` CLI flag** on `scan` / `score` / `test`. The timeout is +a per-target field in a target config file, which you pass with `--target`: + +```json +{ + "targetId": "my-server", + "adapter": "local-process", + "command": "npx", + "args": ["-y", "my-mcp-server"], + "timeoutMs": 30000 +} +``` + +```bash +mcp-observatory scan --target ./my-server.json +``` + +`timeoutMs` works for both `local-process` and `http` adapters. + +Other things to check: + +- **Warm the package cache first.** `npx -y my-mcp-server` on a cold cache + downloads before it starts; run it once by hand so the download isn't inside + the timed window. +- **HTTP targets:** confirm the URL is reachable from this machine, and that any + `authToken` / `headers` in the config are correct — some servers hang rather + than reject when auth is missing. + +--- + +## Tool listing returns empty + +A server that starts but advertises nothing is nearly always missing +configuration. + +- **Required environment variables.** API keys, config paths, workspace roots. + Put them in the target config so the run is reproducible: + + ```json + { + "targetId": "my-server", + "adapter": "local-process", + "command": "npx", + "args": ["-y", "my-mcp-server"], + "env": { "MY_API_KEY": "${MY_API_KEY}" } + } + ``` + + `${VAR}` is expanded from your environment, so no secret is written to the + file. + +- **Try the server standalone first.** If it doesn't list tools outside + `mcp-observatory`, the problem is the server or its config, not the scan: + + ```bash + npx -y my-mcp-server + ``` + +- **Read the raw evidence.** There is no `--verbose` flag; use the JSON output, + which carries per-check evidence and any fatal error the run captured: + + ```bash + mcp-observatory scan --format json npx -y my-mcp-server + ``` + +- **Some servers only expose tools after a workspace argument** (a directory, a + repository, a database URL). Check the server's own README for required + positional arguments. + +--- + +## Rate limiting errors + +Usually the *upstream API* a server wraps, not `mcp-observatory` itself. + +- Scans invoke tools when `--invoke-tools` (or `score`, which enables it) is + used. If the tools call a metered API, each run costs quota. +- Use `skipInvoke: true` in the target config to check capability listings + without calling any tool. +- If you're scanning many servers, space the runs out rather than looping + immediately — `watch --interval ` exists for scheduled re-scans. + +--- + +## Still stuck? + +Include the following when opening an issue: + +- the exact command you ran, +- `mcp-observatory --version` and `node --version`, +- the JSON output (`--format json`), with any secrets redacted. + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to file a good report.