WFDASH-WEBAPP/docs/bugs/2026-08-04-mcp-initialize-handshake-missing.md

# Bug: WFDASH MCP endpoint silently failed the `initialize` handshake

**Status:** ✅ Fixed 2026-08-04 in commit fixing `src/app/api/mcp/route.ts`.
**Severity:** High — every spec-compliant MCP client silently failed to connect.
**Discovery:** Live server logs from a Hermes agent deployment after the `wfdash` MCP server was added to its config.
**Reporter:** Giellie (the WFDASH agent) at the operator's request.

---

## Symptom

A spec-compliant MCP client (Hermes in this case, but the same would apply to Claude Desktop, Cursor, mcp-cli, or any other) configured with:

```yaml
mcp_servers:
  wfdash:
    type: http
    url: https://wfdash.apphub.co.za/api/mcp
    headers:
      Authorization: "Bearer 50e15d09…b1"
    enabled: true
```

…would log:

```
WARNING tools.mcp_tool: MCP server 'wfdash' initial connection failed (attempt 1/3),
retrying in 1s: unhandled errors in a TaskGroup (1 sub-exception)
WARNING tools.mcp_tool: MCP server 'wfdash' initial connection failed (attempt 2/3),
retrying in 2s: unhandled errors in a TaskGroup (1 sub-exception)
WARNING tools.mcp_tool: MCP server 'wfdash' initial connection failed (attempt 3/3),
retrying in 4s: unhandled errors in a TaskGroup (1 sub-exception)
WARNING tools.mcp_tool: MCP server 'wfdash' failed initial connection after 3 attempts,
giving up: unhandled errors in a TaskGroup (1 sub-exception)
WARNING tools.mcp_tool: Failed to connect to MCP server 'wfdash': Session terminated
INFO tools.mcp_tool: MCP: registered 0 tool(s) from 0 server(s) (1 failed)
```

The Hermes WebUI would show:

> **MCP Servers** → `wfdash` → HTTP → CONFIGURED → **0 tools**

…and the agent runtime would have no `wfdash__*` tools available.

## Root cause

`/api/mcp` only handled two JSON-RPC methods:

- `tools/list`
- `tools/call`

The MCP protocol requires a three-step handshake before either of those:

1. Client → Server: `{"method": "initialize", "params": {protocolVersion, capabilities, clientInfo}}`
2. Server → Client: `{"result": {protocolVersion, capabilities, serverInfo}}`
3. Client → Server: `{"method": "notifications/initialized"}` (notification, no `id`)

When Hermes sent step 1, our route fell through to the catch-all:

```ts
return NextResponse.json(
  { jsonrpc: "2.0", id: body?.id ?? null, error: { code: -32601, message: "Method not found" } },
  { status: 404 }   // ← this is the killer
);
```

A spec-compliant MCP client interprets HTTP 404 as "this URL is not an MCP server" and terminates the session immediately — never reaching `tools/list`. Hence 0 tools registered.

This was masked during earlier testing because we (and previous operators) hit `tools/list` directly via `curl` or the Giellie skill — the loose JSON-RPC clients (or skill-based LLM context) didn't care about the missing handshake, but real MCP clients do.

## Fix

Three new handlers in `src/app/api/mcp/route.ts`, added before the `tools/list` dispatch:

```ts
if (body?.method === "initialize") {
  // Plain object — NOT wrapped in the tools/call content envelope
  // (jsonRpcOk wraps in {content: [{type:"text", text: JSON.stringify(...)}]},
  //  which would still break clients).
  return NextResponse.json({
    jsonrpc: "2.0",
    id: body.id ?? null,
    result: {
      protocolVersion: body?.params?.protocolVersion || "2024-11-05",
      capabilities: { tools: {} },
      serverInfo: { name: "wfdash-mcp", version: "1.0.0" },
    },
  });
}
if (body?.method === "notifications/initialized") {
  return new NextResponse(null, { status: 204 });
}
if (body?.method === "ping") {
  return NextResponse.json({
    jsonrpc: "2.0",
    id: body.id ?? null,
    result: {},
  });
}
```

Key detail: the `initialize` response must use a **plain object** for `result`, not the `content: [{type:"text", text: JSON.stringify(...)}]` envelope that our `jsonRpcOk` helper wraps around `tools/list` / `tools/call` results. Using `jsonRpcOk` here would have left the handshake broken in a different way (the protocolVersion would have ended up at `result.content[0].text`, not `result.protocolVersion`).

## Tests

Four new Vitest cases in `src/app/api/mcp/route.test.ts`:

- `handles MCP initialize handshake and returns server info (regression: 2026-08-04)` — confirms HTTP 200, correct result shape, echo of client-provided protocolVersion
- `initialize echoes back an unrecognised protocolVersion so older clients keep working` — confirms we don't hard-pin a version
- `acknowledges notifications/initialized with HTTP 204 and no body` — confirms the notification returns empty
- `answers ping with an empty result (liveness probe)` — confirms `ping` returns `{ result: {} }`

Total: 46 tests, all passing.

## How to verify after redeploy

From any terminal with internet access:

```bash
curl -sS -X POST https://wfdash.apphub.co.za/api/mcp \
  -H "Authorization: Bearer 50e15d097fe85023fed7bb29340347befa224afda83cb270d89cdfa3c8299cb1" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}'
```

Expected (HTTP 200):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "wfdash-mcp", "version": "1.0.0" }
  }
}
```

Then in your Hermes WebUI (or any MCP client configured against this URL), the `wfdash` server's tool count should go from `0` to **69**.

## Lessons / things to look for in other endpoints

- **Check every JSON-RPC server we expose** for the standard method list. `initialize` and `notifications/initialized` are mandatory. Other useful ones to add if we ever extend scope: `prompts/list`, `prompts/get`, `resources/list`, `resources/read`, `logging/setLevel`.
- **Don't reuse the `tools/call` content envelope** for non-`tools/call` methods. `initialize` and `ping` want a plain object result. Consider extracting a separate `jsonRpcResultOk(id, result)` helper to make the right pattern the default.
- **HTTP 404 ≠ "method not implemented"** in MCP-land. Clients use 404 as a signal that the endpoint isn't an MCP server at all. The catch-all for unknown methods should return HTTP 200 with `error.code = -32601`, not HTTP 404.