Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

fix(mcp): fall back when project MCP discover returns -32601

Cursor Agent2fa6d1369e30
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index dbc230a1..cb0b36fe 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,14 @@
+## 2026-09-14 — Project MCP HTTP discover falls back on JSON-RPC -32601
+
+`project_mcp_tools` probed modern `server/discover` and treated only HTTP 400/404/405
+as unsupported. A legacy-only HTTP MCP that answers JSON-RPC method-not-found on HTTP 200
+— the usual JSON-RPC wire — entered the fallback branch and then threw `-32601` because
+the status was not 4xx. HTTP project MCP now treats `-32601` and modern-protocol refusal
+(`-32022`) as unsupported regardless of HTTP 200 vs 4xx, then continues with legacy
+`initialize` + `tools/list`. Malformed-request codes still fail closed. SSRF, exact
+endpoint match and credential scrubbing are unchanged. A Batonly-like server does not
+need to implement `server/discover`.
+
## 2026-09-13 — About version detection without systemd
An installation on a non-systemd host was thirteen commits behind origin/main, but
diff --git a/docs/PROJECT-MCP-CONNECTIONS.md b/docs/PROJECT-MCP-CONNECTIONS.md
index c0f6b3e3..37728005 100644
--- a/docs/PROJECT-MCP-CONNECTIONS.md
+++ b/docs/PROJECT-MCP-CONNECTIONS.md
@@ -52,8 +52,11 @@ The legacy aggregate helper still stops after eight upstream pages and fails exp
if incomplete. Downstream responses are bounded to 2 MiB; an individually very large
descriptor may exceed the preferred 48 KiB page budget.
-HTTP probes modern server/discover once and falls back to legacy initialize when unsupported.
-Modern stdio is opt-in with protocolVersion: 2026-07-28. Rich image/audio/resource results
+HTTP probes modern `server/discover` once. JSON-RPC `-32601` (method not found),
+modern-protocol refusal (`-32022`), and HTTP 400/404/405 without a malformed-request
+error fall back to legacy `initialize` + `tools/list`. A JSON-RPC error on HTTP 200
+is treated as unsupported, not a hard failure. Modern stdio is opt-in with
+protocolVersion: 2026-07-28. Rich image/audio/resource results
are preserved; downstream UI metadata is namespaced rather than trusted as MSO UI origins.
Use Integrations → Add MCP or project_mcp_manage to register an HTTPS endpoint with
diff --git a/lib/host/project-mcp-auth.test.ts b/lib/host/project-mcp-auth.test.ts
index 9ddf27ff..7db6a5d8 100644
--- a/lib/host/project-mcp-auth.test.ts
+++ b/lib/host/project-mcp-auth.test.ts
@@ -1,10 +1,10 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
-const state = vi.hoisted(() => ({ values: { endpoint: "https://app.example/mcp", accessToken: "private-downstream-token", allowedTools: "read_project" } as Record<string, string>, calls: [] as Record<string, unknown>[], paging: "" }));
+const state = vi.hoisted(() => ({ values: { endpoint: "https://app.example/mcp", accessToken: "private-downstream-token", allowedTools: "read_project" } as Record<string, string>, calls: [] as Record<string, unknown>[], paging: "", discoverStatus: 400 }));
vi.mock("@/lib/infra/connection-service", () => ({ directConnectionValues: vi.fn(async () => state.values) }));
vi.mock("./ssrf", () => ({ safeProviderFetch: vi.fn(async (_url, init) => {
const payload = JSON.parse(init.body);
state.calls.push({ ...payload, auth: new Headers(init.headers).get("authorization") });
- if (payload.method === "server/discover") return new Response(JSON.stringify({ jsonrpc: "2.0", id: payload.id, error: { code: -32601, message: "legacy" } }), { status: 400 });
+ if (payload.method === "server/discover") return new Response(JSON.stringify({ jsonrpc: "2.0", id: payload.id, error: { code: -32601, message: "Method not found" } }), { status: state.discoverStatus });
if (payload.method === "tools/list" && state.paging) {
const second = Boolean(payload.params?.cursor);
return new Response(JSON.stringify({ jsonrpc: "2.0", id: payload.id, result: {
@@ -23,9 +23,21 @@ import { normalizeMcpEndpoint, parseMcpToolAllowlist } from "@/lib/infra/mcp-pol
import type { ProjectMcpServer } from "./project-mcp-config";
const server: ProjectMcpServer = { name: "app", transport: "http", url: "https://app.example/mcp", headers: {}, oauthConfigured: false, integration: { user: "owner", connection: "assistant" } };
-beforeEach(() => { state.calls = []; state.paging = ""; state.values = { endpoint: "https://app.example/mcp", accessToken: "private-downstream-token", allowedTools: "read_project" }; });
+beforeEach(() => { state.calls = []; state.paging = ""; state.discoverStatus = 400; state.values = { endpoint: "https://app.example/mcp", accessToken: "private-downstream-token", allowedTools: "read_project" }; });
describe("private modular MCP connection", () => {
+ it("falls back from HTTP 200 method-not-found when the private token is verified", async () => {
+ state.discoverStatus = 200;
+ const url = "https://app.example/mcp/http200";
+ state.values.endpoint = url;
+ const tools = await listMcpServerTools({ ...server, url } as ProjectMcpServer);
+ expect(tools.map((tool) => tool.name)).toEqual(["read_project"]);
+ expect(state.calls[0]).toMatchObject({ method: "server/discover", auth: "Bearer private-downstream-token" });
+ expect(state.calls.some((call) => call.method === "initialize")).toBe(true);
+ const result = await callMcpServerTool({ ...server, url } as ProjectMcpServer, "read_project", {});
+ expect(JSON.stringify({ tools, result })).not.toContain("private-downstream-token");
+ expect(JSON.stringify(result)).toContain("[redacted]");
+ });
it("discovers only granted tools and authenticates without returning the credential", async () => {
expect((await listMcpServerTools(server)).map((tool) => tool.name)).toEqual(["read_project"]);
expect(state.calls.every((call) => call.auth === "Bearer private-downstream-token")).toBe(true);
diff --git a/lib/host/project-mcp-http.test.ts b/lib/host/project-mcp-http.test.ts
index 5ee5f8fd..6e340ae9 100644
--- a/lib/host/project-mcp-http.test.ts
+++ b/lib/host/project-mcp-http.test.ts
@@ -1,27 +1,66 @@
import { beforeEach, expect, it, vi } from "vitest";
-const state = vi.hoisted(() => ({ calls: [] as Array<{ method: string; headers: Headers; params: Record<string, unknown> }>, serial: 0 }));
+type Mode = "modern" | "method-not-found" | "http-404" | "protocol-unsupported" | "invalid-params";
+const state = vi.hoisted(() => ({ calls: [] as Array<{ method: string; headers: Headers; params: Record<string, unknown> }>, serial: 0, mode: "modern" as Mode }));
+function rpcResult(id: unknown, result: unknown, extra: HeadersInit = {}, status = 200) {
+ return new Response(JSON.stringify({ jsonrpc: "2.0", id, result }), { status, headers: { "content-type": "application/json", ...extra } });
+}
+function rpcError(id: unknown, code: number, message: string, status = 200) {
+ return new Response(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }), { status, headers: { "content-type": "application/json" } });
+}
vi.mock("./ssrf", () => ({ safeProviderFetch: vi.fn(async (_url, init) => {
- const body = JSON.parse(init.body), headers = new Headers(init.headers); state.calls.push({ method: body.method, headers, params: body.params });
- const result = body.method === "server/discover" ? { supportedVersions: ["2026-07-28"], capabilities: { tools: {} } } : body.method === "tools/list" ? { tools: [
+ const body = JSON.parse(init.body), headers = new Headers(init.headers); state.calls.push({ method: body.method, headers, params: body.params ?? {} });
+ if (body.method === "server/discover") {
+ if (state.mode === "method-not-found") return rpcError(body.id, -32601, "Method not found");
+ if (state.mode === "http-404") return rpcError(body.id, -32601, "Method not found", 404);
+ if (state.mode === "protocol-unsupported") return rpcError(body.id, -32022, "unsupported MCP protocol version", 400);
+ if (state.mode === "invalid-params") return rpcError(body.id, -32602, "invalid params", 400);
+ return rpcResult(body.id, { resultType: "complete", supportedVersions: ["2026-07-28"], capabilities: { tools: {} } });
+ }
+ if (body.method === "initialize") return rpcResult(body.id, { protocolVersion: "2025-06-18", capabilities: { tools: {} } }, { "mcp-session-id": "legacy-session" });
+ if (body.method === "notifications/initialized") return new Response(null, { status: 202 });
+ const result = body.method === "tools/list" ? { tools: [
{ name: "echo", inputSchema: { type: "object", properties: { context: { type: "object", properties: { region: { type: "string", "x-mcp-header": "Region" } } } } } },
{ name: "bad", inputSchema: { type: "object", properties: { amount: { type: "number", "x-mcp-header": "Amount" } } } },
] } : { content: [{ type: "text", text: "done" }], isError: false };
- return Response.json({ jsonrpc: "2.0", id: body.id, result: { resultType: "complete", ...result } });
+ return rpcResult(body.id, state.mode === "modern" ? { resultType: "complete", ...result } : result);
}) }));
import { withHttp } from "./project-mcp-http";
import { mcpHeaderBindings, mcpArgumentHeaders } from "./project-mcp-headers";
-beforeEach(() => { state.calls = []; state.serial++; });
+function server() { return { name: "fixture", transport: "http" as const, url: "https://example.test/mcp/" + state.serial, headers: {}, oauthConfigured: false }; }
+beforeEach(() => { state.calls = []; state.serial++; state.mode = "modern"; });
it("negotiates modern HTTP once, filters invalid header schemas and mirrors nested Unicode arguments", async () => {
- const server = { name: "modern", transport: "http" as const, url: "https://example.test/mcp/" + state.serial, headers: {}, oauthConfigured: false };
- const list = await withHttp(server, rpc => rpc("tools/list", {}));
+ const list = await withHttp(server(), rpc => rpc("tools/list", {}));
expect((list.result as { tools: unknown[] }).tools).toHaveLength(1);
- await withHttp(server, rpc => rpc("tools/call", { name: "echo", arguments: { context: { region: " 東京 " } } }));
+ await withHttp(server(), rpc => rpc("tools/call", { name: "echo", arguments: { context: { region: " 東京 " } } }));
expect(state.calls.map(c => c.method)).toEqual(["server/discover", "tools/list", "tools/call"]);
const call = state.calls.at(-1)!;
expect(call.headers.get("Mcp-Param-Region")).toBe("=?base64?" + Buffer.from(" 東京 ").toString("base64") + "?=");
expect(call.headers.get("Mcp-Session-Id")).toBeNull();
expect(call.params._meta).toMatchObject({ "io.modelcontextprotocol/clientCapabilities": {} });
});
+it("falls back to initialize when discover returns JSON-RPC -32601 on HTTP 200", async () => {
+ state.mode = "method-not-found";
+ const list = await withHttp(server(), rpc => rpc("tools/list", {}));
+ expect((list.result as { tools: unknown[] }).tools).toHaveLength(2);
+ expect(state.calls.map(c => c.method)).toEqual(["server/discover", "initialize", "notifications/initialized", "tools/list"]);
+ expect(state.calls[0].headers.get("MCP-Protocol-Version")).toBe("2026-07-28");
+ expect(state.calls.find(c => c.method === "initialize")?.params._meta).toBeUndefined();
+ expect(state.calls.at(-1)!.headers.get("Mcp-Session-Id")).toBe("legacy-session");
+ expect(JSON.stringify(list)).not.toMatch(/token|secret|authorization/i);
+});
+it("falls back when modern discover is HTTP 404 method-not-found or protocol-version refusal", async () => {
+ for (const mode of ["http-404", "protocol-unsupported"] as const) {
+ state.calls = []; state.serial++; state.mode = mode;
+ const list = await withHttp(server(), rpc => rpc("tools/list", {}));
+ expect((list.result as { tools: { name: string }[] }).tools.map(t => t.name)).toEqual(["echo", "bad"]);
+ expect(state.calls.map(c => c.method)).toEqual(["server/discover", "initialize", "notifications/initialized", "tools/list"]);
+ }
+});
+it("does not treat malformed modern discover params as an unsupported-method fallback", async () => {
+ state.mode = "invalid-params";
+ await expect(withHttp(server(), rpc => rpc("tools/list", {}))).rejects.toThrow(/-32602/);
+ expect(state.calls.map(c => c.method)).toEqual(["server/discover"]);
+});
it("rejects duplicate/composition annotations and unsafe integer values", () => {
expect(() => mcpHeaderBindings({ properties: { a: { type: "string", "x-mcp-header": "X" }, b: { type: "string", "x-mcp-header": "x" } } })).toThrow();
expect(() => mcpHeaderBindings({ oneOf: [{ properties: { a: { type: "string", "x-mcp-header": "X" } } }] })).toThrow();
diff --git a/lib/host/project-mcp-http.ts b/lib/host/project-mcp-http.ts
index 044467e1..b6302a11 100644
--- a/lib/host/project-mcp-http.ts
+++ b/lib/host/project-mcp-http.ts
@@ -46,6 +46,12 @@ function complete(message: Rpc) {
failure(message);
if (!object(message.result) || message.result.resultType !== "complete") throw new Error("modern MCP result must be complete; input_required is unsupported by this connection");
}
+/** JSON-RPC method-not-found and modern-protocol refusal mean "try initialize", including HTTP 200. */
+function modernDiscoverUnsupported(status: number, error?: { code?: number }): boolean {
+ const code = error?.code;
+ if (code === -32601 || code === -32022) return true;
+ return [400, 404, 405].includes(status) && code !== -32020 && code !== -32602;
+}
export async function withHttp<T>(server: Server, work: (rpc: (method: string, params?: unknown) => Promise<Rpc>) => Promise<T>): Promise<T> {
if (server.oauthConfigured && !Object.keys(server.headers).some(name => name.toLowerCase() === "authorization")) throw new Error("project MCP OAuth requires a private server-side authorization connection");
const deadline = Date.now() + 15_000, key = createHash("sha256").update(JSON.stringify(server)).digest("hex");
@@ -54,9 +60,7 @@ export async function withHttp<T>(server: Server, work: (rpc: (method: string, p
if (!connection) {
connection = { protocol: MODERN, until: Date.now() + 30_000, tools: new Map() };
const probe = await post(server, "server/discover", {}, connection, deadline);
- if (probe.status >= 400 || probe.message.error && ![-32022, -32020, -32602].includes(probe.message.error.code ?? 0)) {
- if (probe.message.error?.code === -32022) throw new Error("downstream MCP requires an unsupported modern protocol version");
- if (![400, 404, 405].includes(probe.status) || probe.message.error && [-32020, -32602].includes(probe.message.error.code ?? 0)) failure(probe.message);
+ if (modernDiscoverUnsupported(probe.status, probe.message.error)) {
connection.protocol = LEGACY;
const init = await post(server, "initialize", { protocolVersion: LEGACY, capabilities: {}, clientInfo: { name: "mso-project-mcp", version: "2" } }, connection, deadline);
failure(init.message);