Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions docs/errors/MCPX_CONFIG_INVALID_COMMAND.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
id: MCPX_CONFIG_INVALID_COMMAND
title: MCPX_CONFIG_INVALID_COMMAND
sidebar_label: INVALID_COMMAND
description: A stdio server's command and args cannot spawn anything — typically a package runner with no package to run.
---

# `MCPX_CONFIG_INVALID_COMMAND`

**Severity:** error
**Domain:** Config

## What happened

The server's `command` / `args` pair cannot start an MCP server. The common case
is a package runner named with nothing to run:

```jsonc
{
"name": "demo-filesystem",
"protocol": "stdio",
"command": "npx" // ← no "args", so there is no package to execute
}
```

`npx`, `uvx`, `pipx` and `bunx` all take the package to run as their first
argument. Without it they either print usage and exit or drop into an
interactive prompt, and neither speaks MCP — so the connection fails on every
attempt and the server stays permanently unhealthy.

mcpproxy detects this *before* spawning the process, which is why the failure is
instant rather than a timeout.

## How to fix

### Add the package to `args`

```jsonc
{
"name": "demo-filesystem",
"protocol": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/serve"]
}
```

`-y` (npm) skips the install prompt, which would otherwise hang the handshake.
The `uvx` equivalent needs no flag:

```jsonc
{ "command": "uvx", "args": ["mcp-server-time"] }
```

### Inspect what is currently configured

```bash
mcpproxy upstream get <server> -o json
```

### Remove the entry if it is a leftover

An entry that was added for a demo or a test and never completed is worth
deleting rather than fixing — it keeps the tray badge red for a server nobody
uses:

```bash
mcpproxy upstream remove <server>
```

### Apply the change

The config file is hot-reloaded, so saving `~/.mcpproxy/mcp_config.json` is
enough. To force a retry immediately:

```bash
mcpproxy upstream restart <server>
```

## Related

- [`MCPX_STDIO_SPAWN_ENOENT`](MCPX_STDIO_SPAWN_ENOENT.md) — the command itself was not found
- [`MCPX_CONFIG_PARSE_ERROR`](MCPX_CONFIG_PARSE_ERROR.md) — the config file is not valid JSON
63 changes: 63 additions & 0 deletions docs/errors/MCPX_HTTP_LEGACY_SSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
id: MCPX_HTTP_LEGACY_SSE
title: MCPX_HTTP_LEGACY_SSE
sidebar_label: LEGACY_SSE
description: The endpoint rejected the streamable-HTTP initialize POST with a 4xx — the signature of a server that only speaks the older SSE transport.
---

# `MCPX_HTTP_LEGACY_SSE`

**Severity:** error
**Domain:** HTTP

## What happened

mcpproxy opened the connection with a streamable-HTTP `initialize` POST and the
endpoint answered with a 4xx. That combination is the signature of a server
implementing only the **older SSE transport**, which expects a `GET` to open an
event stream and a separate POST endpoint for messages — so it rejects the
streamable-HTTP handshake outright.

This is a **transport mismatch, not an authentication or routing failure**. It
is reported separately from `MCPX_HTTP_403` / `MCPX_HTTP_404` precisely because
those send you looking for a credential or URL problem that does not exist.

## How to fix

### Set the transport explicitly

```jsonc
{
"name": "my-server",
"protocol": "sse", // was "http" or "streamable-http"
"url": "https://example.com/sse"
}
```

### Check the URL path

Legacy SSE servers usually publish the stream on a distinct path. If the
endpoint documents `/sse` and the config points at `/mcp` (or the bare origin),
correct the URL as well as the protocol.

### Let mcpproxy pick

Omitting `protocol`, or setting it to `auto`, makes mcpproxy negotiate — useful
when the server supports both and you do not want to pin a choice:

```jsonc
{ "name": "my-server", "protocol": "auto", "url": "https://example.com/mcp" }
```

### Confirm the change

```bash
mcpproxy upstream restart <server>
mcpproxy upstream logs <server> --follow
```

## Related

- [`MCPX_HTTP_404`](MCPX_HTTP_404.md) — the endpoint genuinely does not exist
- [`MCPX_HTTP_403`](MCPX_HTTP_403.md) — the endpoint exists but refuses the caller
- [`MCPX_HTTP_CONN_REFUSED`](MCPX_HTTP_CONN_REFUSED.md) — nothing is listening at all
2 changes: 2 additions & 0 deletions docs/errors/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ Run `mcpproxy doctor list-codes` for the machine-readable list.
- [`MCPX_HTTP_404`](MCPX_HTTP_404.md) — Not Found
- [`MCPX_HTTP_5XX`](MCPX_HTTP_5XX.md) — Server error
- [`MCPX_HTTP_CONN_REFUSED`](MCPX_HTTP_CONN_REFUSED.md) — Connection refused
- [`MCPX_HTTP_LEGACY_SSE`](MCPX_HTTP_LEGACY_SSE.md) — endpoint only speaks the legacy SSE transport

## Docker

Expand All @@ -77,6 +78,7 @@ Run `mcpproxy doctor list-codes` for the machine-readable list.
- [`MCPX_CONFIG_DEPRECATED_FIELD`](MCPX_CONFIG_DEPRECATED_FIELD.md) — deprecated field used
- [`MCPX_CONFIG_PARSE_ERROR`](MCPX_CONFIG_PARSE_ERROR.md) — invalid JSON
- [`MCPX_CONFIG_MISSING_SECRET`](MCPX_CONFIG_MISSING_SECRET.md) — secret reference unresolved
- [`MCPX_CONFIG_INVALID_COMMAND`](MCPX_CONFIG_INVALID_COMMAND.md) — command has nothing to run (e.g. `npx` with no package)

## Quarantine

Expand Down
27 changes: 27 additions & 0 deletions internal/diagnostics/classifier.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import (
"os/exec"
"strings"
"syscall"

"github.com/mark3labs/mcp-go/client/transport"
)

// Classify maps a raw error to a stable Code. It prefers typed-error inspection
Expand Down Expand Up @@ -157,6 +159,13 @@ func classifyConfig(err error, _ ClassifierHints) Code {
strings.Contains(msg, "secret reference") && (strings.Contains(msg, "not found") || strings.Contains(msg, "unresolved")),
strings.Contains(msg, "unresolved secret"):
return ConfigMissingSecret
// A package-runner command with nothing to run. This is mcpproxy's OWN
// pre-spawn validation message (internal/upstream/core/connection_stdio.go),
// so leaving it unclassified put a "Please file a bug report" CTA on a
// config typo the user can fix in one line.
case strings.Contains(msg, "has no args"),
strings.Contains(msg, "no args") && strings.Contains(msg, "required"):
return ConfigInvalidCommand
}
return ""
}
Expand Down Expand Up @@ -346,6 +355,24 @@ func classifyHTTP(err error, hints ClassifierHints) Code {
return HTTPTimeout
}

// A 4xx on the streamable-HTTP `initialize` POST is the legacy-SSE
// signature, not an auth or routing failure. Matched BEFORE the generic
// status-text fallback below, which would otherwise claim it as a bare
// MCPX_HTTP_404/403 and send the user hunting for a credential problem that
// does not exist.
//
// The typed check first: this error is mcp-go's exported sentinel, NOT one
// of our own strings, so a library bump can reword it at any time. The
// substring fallback stays because the upstream layer commonly stringifies
// the error before it reaches us, which breaks the errors.Is chain.
// TestLegacySSESentinelStillMatches pins the vendored wording so that bump
// fails a test instead of silently regressing this code to MCPX_HTTP_404.
if errors.Is(err, transport.ErrLegacySSEServer) ||
strings.Contains(lmsg, "likely a legacy sse server") ||
(strings.Contains(lmsg, "4xx for initialize") && strings.Contains(lmsg, "post")) {
return HTTPLegacySSE
}

// HTTP status text fallback. The upstream layer wraps non-2xx responses
// as a plain string ("transport error: request failed with status 504: ...").
// The typed statusError path used by DiagnoseHTTPStatus() never fires for
Expand Down
130 changes: 130 additions & 0 deletions internal/diagnostics/classifier_selfmessages_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
package diagnostics

import (
"errors"
"fmt"
"strings"
"testing"

"github.com/mark3labs/mcp-go/client/transport"
)

// Both errors below reached the user as MCPX_UNKNOWN_UNCLASSIFIED, whose catalog
// entry tells them to file a bug report against us — for failures that are
// entirely diagnosable. The strings are copied verbatim from a live v0.61.0
// install.
//
// Only the first is mcpproxy's own wording (internal/upstream/core/
// connection_stdio.go). The second is mcp-go's exported `transport
// .ErrLegacySSEServer` sentinel; see TestLegacySSESentinelStillMatches for why
// that distinction needs its own guard.
func TestOwnErrorMessagesDoNotClassifyAsUnknown(t *testing.T) {
cases := []struct {
name string
err string
hints ClassifierHints
want Code
}{
{
name: "package runner with no package to run",
err: `failed to connect: server "demo-filesystem": command "npx" has no args — the npm package to run (e.g. ["-y", "some-mcp-server"]) is required`,
hints: ClassifierHints{Transport: "stdio"},
want: ConfigInvalidCommand,
},
{
name: "uvx variant of the same validation failure",
err: `server "x": command "uvx" has no args — the Python package to run is required`,
hints: ClassifierHints{Transport: "stdio"},
want: ConfigInvalidCommand,
},
{
name: "streamable-HTTP handshake refused by a legacy SSE server",
err: "failed to connect: MCP initialize failed during no-auth strategy: transport error: server returned 4xx for initialize POST, likely a legacy SSE server",
hints: ClassifierHints{Transport: "http"},
want: HTTPLegacySSE,
},
}

for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := Classify(errors.New(tc.err), tc.hints)
if got != tc.want {
t.Fatalf("Classify() = %q, want %q", got, tc.want)
}
if got == UnknownUnclassified {
t.Fatal("mcpproxy's own error message must never ask the user to file a bug")
}
})
}
}

// The legacy-SSE match must win over the generic HTTP status-text fallback:
// reading it as a bare 403/404 sends the user hunting for a credential problem
// that does not exist.
func TestLegacySSEBeatsGenericStatusText(t *testing.T) {
err := errors.New("transport error: request failed with status 404: server returned 4xx for initialize POST, likely a legacy SSE server")
if got := Classify(err, ClassifierHints{Transport: "http"}); got != HTTPLegacySSE {
t.Fatalf("Classify() = %q, want %q", got, HTTPLegacySSE)
}
}

// Every code the classifier can return must be registered, or the API emits a
// diagnostic with no user message, no fix steps and no docs URL.
func TestNewCodesAreRegistered(t *testing.T) {
for _, c := range []Code{ConfigInvalidCommand, HTTPLegacySSE} {
entry, ok := Get(c)
if !ok {
t.Fatalf("%s is not registered in the catalog", c)
}
if entry.UserMessage == "" {
t.Errorf("%s has no user message", c)
}
if len(entry.FixSteps) == 0 {
t.Errorf("%s has no fix steps", c)
}
for _, step := range entry.FixSteps {
if step.Type == FixStepLink && step.URL == "" {
t.Errorf("%s has a link fix step with no URL", c)
}
}
}
}

// A genuine 404 with no legacy-SSE marker must still classify as a plain 404 —
// the new rule must not swallow the generic HTTP status path.
func TestOrdinaryHTTPStatusesAreUnaffected(t *testing.T) {
err := errors.New("transport error: request failed with status 404: not found")
if got := Classify(err, ClassifierHints{Transport: "http"}); got != HTTPNotFound {
t.Fatalf("Classify() = %q, want %q", got, HTTPNotFound)
}
}

// The legacy-SSE rule matches a string mcp-go owns, not one of ours. Nothing
// else in this repo produces it:
//
// $ grep -rn "legacy SSE" --include="*.go" internal/ | grep -v _test
// internal/diagnostics/classifier.go:... (the matcher itself)
//
// So a routine mcp-go bump that rewords the sentinel would silently regress
// MCPX_HTTP_LEGACY_SSE back to MCPX_HTTP_404 with the whole suite green — the
// user gets sent hunting for a credential problem again. The typed errors.Is
// path in classifyHTTP survives a reword; the substring fallback (needed
// because the upstream layer stringifies the error) does not. This pins it, so
// the bump fails HERE with a clear reason instead of degrading in the field.
func TestLegacySSESentinelStillMatches(t *testing.T) {
msg := strings.ToLower(transport.ErrLegacySSEServer.Error())

matchesWording := strings.Contains(msg, "likely a legacy sse server") ||
(strings.Contains(msg, "4xx for initialize") && strings.Contains(msg, "post"))
if !matchesWording {
t.Fatalf("mcp-go reworded ErrLegacySSEServer to %q — update the substring fallback "+
"in classifyHTTP to match, or MCPX_HTTP_LEGACY_SSE silently degrades to MCPX_HTTP_404",
transport.ErrLegacySSEServer.Error())
}

// The typed path must work even when nothing about the wording matches.
if got := Classify(fmt.Errorf("connect: %w", transport.ErrLegacySSEServer),
ClassifierHints{Transport: "http"}); got != HTTPLegacySSE {
t.Fatalf("wrapped sentinel classified as %q, want %q", got, HTTPLegacySSE)
}
}
12 changes: 12 additions & 0 deletions internal/diagnostics/codes.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,12 @@ const (
HTTPServerErr Code = "MCPX_HTTP_5XX"
HTTPConnRefuse Code = "MCPX_HTTP_CONN_REFUSED"
HTTPTimeout Code = "MCPX_HTTP_TIMEOUT"
// HTTPLegacySSE: the endpoint rejected the streamable-HTTP `initialize`
// POST with a 4xx. That is the signature of a server that only speaks the
// older SSE transport, so the fix is a transport change in config — not a
// credential or reachability problem, which is why it must not fall through
// to a generic MCPX_HTTP_4xx or to MCPX_UNKNOWN_UNCLASSIFIED.
HTTPLegacySSE Code = "MCPX_HTTP_LEGACY_SSE"
)

// DOCKER domain — Docker isolation subsystem failures.
Expand All @@ -74,6 +80,12 @@ const (
ConfigDeprecatedField Code = "MCPX_CONFIG_DEPRECATED_FIELD"
ConfigParseError Code = "MCPX_CONFIG_PARSE_ERROR"
ConfigMissingSecret Code = "MCPX_CONFIG_MISSING_SECRET"
// ConfigInvalidCommand: the server's stdio `command`/`args` pair cannot
// spawn anything useful — e.g. a package-runner (`npx`, `uvx`) with no
// package to run. mcpproxy detects this itself before spawning, so the
// message is ours and the user can fix it in mcp_config.json; surfacing it
// as UNKNOWN told them to file a bug against us instead.
ConfigInvalidCommand Code = "MCPX_CONFIG_INVALID_COMMAND"
)

// QUARANTINE domain — security quarantine failures.
Expand Down
Loading
Loading